# Design Dna

> Extracts a prospect's real brand palette from their public materials, harmonizes it into a WCAG 2.2 AA-audited token set, and fuses it with CETI house rigor so every deliverable feels already theirs. Emits design/tokens.css (the versioned sf-tokens schema every artifact skill consumes) and design/palette.md (provenance + contrast matrix). Use when the user says "design DNA for [company]", "extract their colors", "brand the deliverables for this prospect", "tokens for this client", or automatically as the design stage of any factory run before artifacts are built. Refuses to ship invented colors or failing contrast pairs.

- Skill: `manutej/design-dna` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add manutej/design-dna`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manutej/design-dna/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: manutej (https://skillmd.com/u/manutej)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/manutej/design-dna

---


# Design-dna — the prospect's colors, our rigor

This skill is the **shared design interface** of signal-forge. It produces one palette per
prospect as a versioned token contract (`sf-tokens/1.0`); pitch-deck, demo-forge, dashboards,
docs, workshop-kit, and account-copy consume `design/tokens.css` and define **no colors of
their own**. Get this wrong and every downstream artifact is wrong. Read
`../forge/references/design-rigor.md` (the hybrid rule + QA ladder) and
`../forge/references/evidence-rules.md` (no invented values) — they govern this output.

Full craft lives in three references (read the one you're in):
- **`references/token-schema.md`** — THE contract: every `--sf-*` variable, its semantics,
  constraints, the header format, dark-mode names, and the backward-compatibility rule.
- **`references/extraction-protocol.md`** — fetch surfaces, frequency×prominence tally,
  identity-core rules, provenance format, the failure ladder, per-client caching.
- **`references/harmonization-tree.md`** — the decision tree, ramp generation, WCAG matrix
  procedure, identity-preservation check, and the CETI house-fallback palette.

## Typed input slots (fill at intake; `UNKNOWN` is legal, never invent)

```
PROSPECT_URLS:  list[url] | UNKNOWN   # brand surfaces to extract from
BRAND_ASSETS:   list[path] | none     # supplied logos / brand PDF / guideline deck (outrank the live site)
CLIENT_SLUG:    str                   # per-client isolation + cache key
PRIOR_TOKENS:   path | none           # existing tokens.css → re-extraction (rebrand) path
REGISTER:       {rigor|soft} | rigor  # soft ⇒ prefer owala-colors engine; else dict-color/Wada
```
`PROSPECT_URLS = UNKNOWN` and no `BRAND_ASSETS` ⇒ run the failure ladder; if it dead-ends,
ship the **house-fallback** and log it (never guess a hex).

## Typed outputs

```
design/tokens.css   # sf-tokens/1.0 header + :root (light) + [data-theme="dark"]; every --sf-* name present
design/palette.md   # provenance table · light WCAG matrix · dark WCAG matrix · identity-preservation statement
UNKNOWNS.md (append) # any failed fetch / house-fallback, routed "design-dna"
FACTORY/atoms.md (append) # ≥1 atom: palette outcome and/or new extraction route
```

## Artifact specs + acceptance checklists

**`design/tokens.css`** — measurable spec:
- [ ] Opens with the exact header block from `token-schema.md §1` (`schema:`, `client:`,
      `source:`, `palette:`, `provenance:`, `generated:`, `dark:` lines filled).
- [ ] Defines **every** name in `token-schema.md §8` — no omissions, no extras.
- [ ] `--sf-lead` aliases `--sf-lead-500`; ramp 50→900 is monotonically darkening.
- [ ] `[data-theme="dark"]` rebinds the same names (no `-dark` variables).
- [ ] No hardcoded hex outside `:root`/`[data-theme="dark"]`; shadows tint to anchor, not black.

**`design/palette.md`** — measurable spec:
- [ ] Provenance table: `| hex | role observed | source URL | surface | accessed |` — one row
      per shipped color; derived colors cite their curated palette + combination name.
- [ ] Light contrast matrix table: every required pair (`harmonization-tree.md §D`) with
      ratio + AA verdict; **zero failures**.
- [ ] Dark contrast matrix table: same pairs against the dark twin; **zero failures**.
- [ ] Identity-preservation statement (side-by-side): extracted lead → shipped `--sf-lead`,
      with ΔH (≤8°), chroma, and lightness deltas, ending "same color, better".

## Pipeline (stages with blocking predicates)

### Frame
Read the three references. Fill the input slots. Decide the path: **extract** (URLs/assets
present) or **house-fallback** (ladder dead-ends). If `PRIOR_TOKENS` exists and the brand is
unchanged within the re-extraction cadence (90 days), reuse the cache; a rebrand signal
forces full re-extraction.
> **Predicate F:** input slots filled; path chosen; cache decision logged.

### Do
1. **Extract** (`extraction-protocol.md`): fetch site CSS incl. linked stylesheets, inline
   styles, SVG logo fills, `theme-color`, favicon/manifest, hero. Tally colors by
   frequency×prominence (logo/CTA/header outweigh body). Determine the 1–3 identity-core
   colors. Write a provenance row for every kept color.
   > **Predicate D1:** every candidate color has a source URL + accessed date, or it is dropped.
2. **Harmonize** (`harmonization-tree.md`): assess core quality (muddy / clashing / too many
   / mono); snap onto the nearest Wada combination (`dict-color`) or Owala cast
   (`owala-colors`) per `REGISTER`; assign lead/support/anchor/surfaces/text/semantic;
   generate the OKLCH ramp; pair the dark twin (`dark-mode-pairing` method).
   > **Predicate D2:** every color is sourced (cited) or from a named curated palette (cited);
   > no extracted core color moved > 8° in hue.
3. **Audit** (`harmonization-tree.md §D`): build the WCAG 2.2 AA matrix over the pairs
   artifacts actually use; remediate failures **lightness-only** until zero; repeat for dark.
   Use `owala-design:wcag-contrast` when installed, else compute ratios directly.
   > **Predicate D3:** zero failing pairs in light AND dark.

### Review
Run the identity-preservation check (§E) and the acceptance checklists above. Confirm one
palette per prospect (no artifact defines colors). Confirm the header + provenance are
complete. This maps to the Contrast pass of the QA ladder in `design-rigor.md`.
> **Predicate R:** both checklists pass; identity statement honestly reads "same color, better".

### Capture
Emit `tokens.css` + `palette.md`. Append any fetch failure / fallback to `UNKNOWNS.md`.
Mint ≥1 atom to `FACTORY/atoms.md` via the `mint-atoms` skill (a run that mints none did not
complete): `type: template` (a palette outcome / harmonization that landed), and/or
`type: triage-route` (a new source that resolved a hard extraction). Trace any human color
correction to the line that allowed it (see Feedback below).
> **Predicate C:** outputs written; ≥1 atom minted; fallbacks logged.

## Scale-native operation (N clients)

- **Per-client isolation** — extraction/harmonization for client A never reads client B's
  cache or tokens. The only cross-client shared assets are the **schema** (`token-schema.md`)
  and the **house-fallback palette** (a constant). Runs live under
  `prospects/<slug>/design/`.
- **Token caching** — raw candidate tallies cache under `design/.extract-cache/<slug>.json`,
  keyed by slug + domain + fetch-date.
- **House-token reuse** — neutrals (surfaces/text/anchor) may reuse the house default only
  when the brand supplies nothing better, cited as `CETI house default`.
- **Re-extraction cadence** — 90 days by default; a changed `theme-color`, new logo hash, or
  "they rebranded" invalidates the cache → re-fetch → new `tokens.css` (values change, names
  and schema do not) → **regenerate** dependent artifacts, never hand-patch.
- **Schema stability** — because artifact skills bind only to `--sf-*` names, a per-client
  value change ripples through automatically; only a **rename** breaks them (major version
  bump + migration note).

## Core invariants (H8)

1. Every shipped color is **sourced from the prospect's materials (cited)** or **from a named
   curated palette (cited)** — Wada / JIS / Owala / CETI house default. **No invented values.**
2. `UNKNOWN` inputs and failed extractions are **logged** (UNKNOWNS.md + tokens header
   `client: house-fallback`), never silently defaulted.
3. **One palette per prospect.** Artifacts consume `--sf-*`; none define colors.
4. Extracted identity core survives with **ΔH ≤ 8°** — recognizably their color.
5. Contrast fixes are **lightness-only**; hue is never moved to pass an audit.

## DONE predicate

A design-dna run is DONE when: `tokens.css` defines every `token-schema.md §8` name with a
complete header · `palette.md` carries a full provenance table + light **and** dark WCAG
matrices with **zero failures** · the identity-preservation statement holds (ΔH ≤ 8°) · every
color is sourced or curated-and-cited · any fallback is logged in UNKNOWNS.md · ≥1 atom is
minted.

## Refusal conditions (H9)

Refuse to emit / ship, and surface the blocker, when:
- A required contrast pair fails AA in light or dark and cannot be fixed lightness-only
  without breaking recognizability — **do not ship failing contrast pairs.**
- A color would be **invented** ("brandish" guess) to fill a gap — run the ladder or ship the
  logged house-fallback instead. **Never invent brand colors.**
- Harmonization would move an extracted core hue **> 8°** — that is a different brand.
- An artifact requests a `var(--sf-…)` not in the schema — fix the schema (versioned) or the
  artifact; do not let an undefined token ship.

## Feedback tracing (H10)

When a human corrects the palette ("wrong blue", "too muted", "that's not our green"), route
through `mint-atoms`: log the correction dated with the run slug, then **trace it to the line
that allowed it** — a mis-weighted prominence rule (`extraction-protocol.md §2`), a
harmonization bound (`harmonization-tree.md §A`), or an identity mis-read (§3). Fix at the
line, bump the reference if the fix generalizes, and **regenerate** `tokens.css` +
dependent artifacts from the corrected palette — never hand-patch a hex in one artifact.

## Skill composition

Prefer when installed; degrade to hand-computation to the same standard: `dict-color`
(Wada/JIS harmony engine), `owala-design:owala-colors` (soft register), `…:design-tokens`
(OKLCH token emit), `…:dark-mode-pairing` (dark twin), `…:wcag-contrast` (matrix audit),
`…:layout-rhythm` / `…:motion-curves` (spacing + motion token values).