Design DNA
Most "make it look like this" requests fail the same way: the reference is
looked at once, an impression is formed, and the impression is coded from
memory. What survives is a vague resemblance — the palette drifts, the rhythm
flattens, and the one effect that gave the reference its character is missing
entirely.
This skill inserts an artifact between looking and building. The reference is
first deconstructed into a Design DNA JSON, and only that JSON is used to
generate. The intermediate step is what makes the result checkable: every
colour, radius, and easing curve in the output traces to a recorded field, so a
mismatch is a diff rather than an argument about taste.
Provenance: the three-dimension taxonomy and several extraction rules are
adapted from the MIT-licensed zanwei/design-dna skill. See
.claude/rules/moai/NOTICE.md for the retained copyright notice.
The three dimensions
The split matters because the three are extracted differently and fail
differently.
| Dimension |
What it holds |
How it is obtained |
design_system |
What can be measured — colour hex values, type scale, spacing base unit, radius, elevation, motion timings, component patterns |
Sampled and measured from the reference; numeric |
design_style |
What can be felt — mood, ornamentation level, composition strategy, whitespace philosophy, interaction personality, microcopy tone |
Judged holistically; descriptive words, not numbers |
visual_effects |
What cannot be expressed in plain CSS — Canvas scenes, WebGL / 3D, shaders, particle systems, scroll-driven motion, cursor behaviour, glassmorphism |
Read from source where available, described from screenshots where not |
Collapsing them loses information in both directions. A token dump with no
style dimension reproduces the colours and none of the character; a mood board
with no system dimension reproduces the vibe and no two elements align.
Field-by-field schema and enum vocabularies: references/dna-schema.md.
Phase 1 — Structure
When the request is for the schema itself ("what does a design profile
contain?"), read references/dna-schema.md, present the three dimensions and
their field groups, and ask whether any dimension should be extended or
dropped before extraction begins.
Phase 2 — Analyze (reference → DNA JSON)
Read references/dna-schema.md first, then work reference by reference.
- Image or screenshot → read it directly and analyse its visual properties.
- URL → fetch the page. Prefer the source:
<canvas> elements, WebGL
contexts, animation-library imports, custom shaders, IntersectionObserver
scroll triggers, and SVG <animate> are stated facts, where a screenshot
only supports inference.
- Video or interaction capture → the only reliable source for motion
timings, scroll choreography, and transition personality.
Extraction rules
- Colour roles are assigned by dominance, not by hue. Primary is the
colour holding the most area, secondary the supporting surface, accent
whatever carries the calls to action. Map the neutral scale as an ordered
ramp from the lightest background to the darkest text.
- Measure radius relatively. Record it against the element height that
carries it — an absolute
12px is meaningless once the button is a
different size, while "half the control height" survives rescaling. The
concentric-radius rule for nested surfaces is moai-ref-ui-polish's; do not
restate it here, apply it there.
- Infer type scale from ratios, not from absolute sizes. Heading-to-body
ratio and line-height rhythm transfer across viewports; pixel sizes do not.
- Density is proximity. Judge spacing from element gaps relative to the
base unit, and section rhythm from whether those gaps stay constant or
escalate between sections.
- When references conflict, record the dominant pattern and name the
variant. Averaging two references produces a design neither of them has.
- Fill every field. An empty string is indistinguishable from "not looked
at". Where the reference genuinely does not exercise a field, say so in the
value — an explicit "not observed" is data; a blank is a gap.
- Effects absent from the reference get
enabled: false. This is the
non-invention rule, and it is load-bearing: an unset flag invites the
generator to add a particle field nobody asked for.
- What cannot be identified goes in
composite_notes. A screenshot shows
that a surface glows without showing how. Describing the observation beats
guessing the implementation and recording the guess as fact.
Output the completed JSON, then ask whether any value should be adjusted before
generation.
Phase 3 — Generate (DNA JSON + content → artifact)
Read references/effects-implementation.md before implementing any
visual_effects entry.
Order matters, because early decisions constrain later ones. Colour and
typography together carry most of a design's identity, so they are settled
first; effects are layered onto a design that already works without them.
- Colour and typography
- Spacing and layout
- Shape and elevation
design_style qualitative fields — these guide the judgement calls the
token values do not determine
visual_effects
- Motion and interaction, last: an interface whose static layout is wrong is
not rescued by animating it
Emit design_system as CSS custom properties in a single :root block, so
every downstream value has one definition and a token swap is one edit.
Fetch real assets rather than approximating them. When the reference is a
URL and the design needs its logo, image, or font, retrieve the actual asset
from that source. A recreated approximation is the single most visible
difference between a copy and a clone.
Default output is a self-contained file — inline CSS and JS, no build
step — unless a framework was specified. The self-contained convention itself
is documented once in moai-domain-html-report § output; the difference here
is scope: that skill renders a report from markdown, this one generates a
designed artifact from a DNA profile.
Profile persistence
Phase 2 can end by saving the completed DNA JSON as a named profile, and
Phase 3 can start from the active profile instead of re-extracting the same
reference: references/diagram-profiles.md documents the mechanism — the
project-root .design-dna/ store, the marker-first active selector, the slug
grammar, schema validation with "not observed" backfill on load, and the
confirm-before-overwrite / verify-by-re-read save path. A project with no
profile marker proceeds exactly as above; persistence adds a save hook and a
start-from option, never a routing change.
Delivery gate
Verify before handing over. Each item below has failed in practice.
- Every colour in the output traces to a DNA palette entry.
- Font families, spacing rhythm, and radius match their DNA tokens.
- Body text meets 4.5:1 contrast, large text 3:1.
prefers-reduced-motion: reduce is honoured — not merely detected.
- Nothing renders for an effect whose
enabled flag is false.
- Animation loops use
requestAnimationFrame; setInterval is not an
animation primitive and drifts against the display refresh.
- Canvas and WebGL contexts are sized to their container and handle resize.
- The declared
fallback_strategy is actually implemented, not just recorded.
Polish iteration
A first pass that reads thin is usually not a token problem — it is an
attention problem, and re-reading the reference beats re-reading the output.
Re-attach the same references and audit against them along six axes:
hierarchy, ornamentation, typographic rhythm, motion, materiality, and overall
interface finish. Merge the conclusions back into the current implementation
rather than regenerating from scratch, which discards the parts that were
already right.
Boundaries
| Request |
Owner |
| Markdown report → HTML |
moai-domain-html-report |
| Architecture / flow diagram |
moai-domain-svg-infographic |
| Chart, dashboard, or categorical palette |
dataviz |
| Component-level finish: concentric radius, optical alignment, hit areas, easing craft |
moai-ref-ui-polish |
| Hosted claude.ai visual-identity page |
artifact-design |
| Design-system sync with the Claude Design product |
manager-design |
This skill owns one thing the others do not: turning an existing reference
into a structured profile, and generating from that profile. Where the design
is authored from first principles rather than deconstructed, those skills own
it.
References
references/dna-schema.md — the three-dimension field list and enum vocabularies
references/diagram-profiles.md — named-profile persistence: the .design-dna/ store, marker-first resolution, slug grammar, load-time validation
references/effects-implementation.md — performance tiers, technology selection, and per-effect implementation patterns
1---
2name: moai-domain-design-dna
3description: >
4 Reverse-engineer a reference design — a screenshot, an image set, or a live
5 URL — into a portable Design DNA JSON across three dimensions (measurable
6 tokens, qualitative style, special-rendering effects), then generate a new
7 self-contained artifact from that JSON. Carries the extraction rules
8 (dominance-based colour roles, relative radius measurement, multi-reference
9 conflict resolution), a performance-tier technology map for Canvas / WebGL /
10 shader / scroll effects, and a delivery gate covering contrast, reduced
11 motion, and animation-loop hygiene.
12
13when_to_use: >
14 Use when someone points at an existing design and wants its look captured or
15 reproduced — "build this in the same style as this screenshot", "extract the
16 design tokens from this site", "make a page that feels like this reference" —
17 or when a Design DNA JSON already exists and a new artifact must be generated
18 from it. Not for report rendering (moai-domain-html-report), static diagrams
19 (moai-domain-svg-infographic), or charts (dataviz).
20
21license: Apache-2.0
22compatibility: Designed for Claude Code
23allowed-tools: Read, Write, Edit, Grep, Glob, WebFetch, Bash
24user-invocable: true
25metadata:
26 source: https://skillmd.com/skills/modu-ai/moai-domain-design-dna
27 version: "1.0.0"
28 category: domain
29 status: active
30 related-skills: moai-ref-ui-polish, moai-domain-html-report, moai-domain-svg-infographic
31---
32
33# Design DNA
34
35Most "make it look like this" requests fail the same way: the reference is
36looked at once, an impression is formed, and the impression is coded from
37memory. What survives is a vague resemblance — the palette drifts, the rhythm
38flattens, and the one effect that gave the reference its character is missing
39entirely.
40
41This skill inserts an artifact between looking and building. The reference is
42first deconstructed into a **Design DNA JSON**, and only that JSON is used to
43generate. The intermediate step is what makes the result checkable: every
44colour, radius, and easing curve in the output traces to a recorded field, so a
45mismatch is a diff rather than an argument about taste.
46
47> **Provenance**: the three-dimension taxonomy and several extraction rules are
48> adapted from the MIT-licensed `zanwei/design-dna` skill. See
49> `.claude/rules/moai/NOTICE.md` for the retained copyright notice.
50
51## The three dimensions
52
53The split matters because the three are extracted differently and fail
54differently.
55
56| Dimension | What it holds | How it is obtained |
57|---|---|---|
58| `design_system` | What can be **measured** — colour hex values, type scale, spacing base unit, radius, elevation, motion timings, component patterns | Sampled and measured from the reference; numeric |
59| `design_style` | What can be **felt** — mood, ornamentation level, composition strategy, whitespace philosophy, interaction personality, microcopy tone | Judged holistically; descriptive words, not numbers |
60| `visual_effects` | What **cannot be expressed in plain CSS** — Canvas scenes, WebGL / 3D, shaders, particle systems, scroll-driven motion, cursor behaviour, glassmorphism | Read from source where available, described from screenshots where not |
61
62Collapsing them loses information in both directions. A token dump with no
63style dimension reproduces the colours and none of the character; a mood board
64with no system dimension reproduces the vibe and no two elements align.
65
66Field-by-field schema and enum vocabularies: `references/dna-schema.md`.
67
68## Phase 1 — Structure
69
70When the request is for the schema itself ("what does a design profile
71contain?"), read `references/dna-schema.md`, present the three dimensions and
72their field groups, and ask whether any dimension should be extended or
73dropped before extraction begins.
74
75## Phase 2 — Analyze (reference → DNA JSON)
76
77Read `references/dna-schema.md` first, then work reference by reference.
78
79- **Image or screenshot** → read it directly and analyse its visual properties.
80- **URL** → fetch the page. Prefer the source: `<canvas>` elements, WebGL
81 contexts, animation-library imports, custom shaders, `IntersectionObserver`
82 scroll triggers, and SVG `<animate>` are *stated* facts, where a screenshot
83 only supports inference.
84- **Video or interaction capture** → the only reliable source for motion
85 timings, scroll choreography, and transition personality.
86
87### Extraction rules
88
891. **Colour roles are assigned by dominance, not by hue.** Primary is the
90 colour holding the most area, secondary the supporting surface, accent
91 whatever carries the calls to action. Map the neutral scale as an ordered
92 ramp from the lightest background to the darkest text.
932. **Measure radius relatively.** Record it against the element height that
94 carries it — an absolute `12px` is meaningless once the button is a
95 different size, while "half the control height" survives rescaling. The
96 concentric-radius rule for nested surfaces is `moai-ref-ui-polish`'s; do not
97 restate it here, apply it there.
983. **Infer type scale from ratios**, not from absolute sizes. Heading-to-body
99 ratio and line-height rhythm transfer across viewports; pixel sizes do not.
1004. **Density is proximity.** Judge spacing from element gaps relative to the
101 base unit, and section rhythm from whether those gaps stay constant or
102 escalate between sections.
1035. **When references conflict, record the dominant pattern and name the
104 variant.** Averaging two references produces a design neither of them has.
1056. **Fill every field.** An empty string is indistinguishable from "not looked
106 at". Where the reference genuinely does not exercise a field, say so in the
107 value — an explicit "not observed" is data; a blank is a gap.
1087. **Effects absent from the reference get `enabled: false`.** This is the
109 non-invention rule, and it is load-bearing: an unset flag invites the
110 generator to add a particle field nobody asked for.
1118. **What cannot be identified goes in `composite_notes`.** A screenshot shows
112 that a surface glows without showing how. Describing the observation beats
113 guessing the implementation and recording the guess as fact.
114
115Output the completed JSON, then ask whether any value should be adjusted before
116generation.
117
118## Phase 3 — Generate (DNA JSON + content → artifact)
119
120Read `references/effects-implementation.md` before implementing any
121`visual_effects` entry.
122
123**Order matters, because early decisions constrain later ones.** Colour and
124typography together carry most of a design's identity, so they are settled
125first; effects are layered onto a design that already works without them.
126
1271. Colour and typography
1282. Spacing and layout
1293. Shape and elevation
1304. `design_style` qualitative fields — these guide the judgement calls the
131 token values do not determine
1325. `visual_effects`
1336. Motion and interaction, last: an interface whose static layout is wrong is
134 not rescued by animating it
135
136Emit `design_system` as CSS custom properties in a single `:root` block, so
137every downstream value has one definition and a token swap is one edit.
138
139**Fetch real assets rather than approximating them.** When the reference is a
140URL and the design needs its logo, image, or font, retrieve the actual asset
141from that source. A recreated approximation is the single most visible
142difference between a copy and a clone.
143
144**Default output is a self-contained file** — inline CSS and JS, no build
145step — unless a framework was specified. The self-contained convention itself
146is documented once in `moai-domain-html-report` § output; the difference here
147is scope: that skill renders a *report* from markdown, this one generates a
148*designed artifact* from a DNA profile.
149
150## Profile persistence
151
152Phase 2 can end by saving the completed DNA JSON as a **named profile**, and
153Phase 3 can start from the **active profile** instead of re-extracting the same
154reference: `references/diagram-profiles.md` documents the mechanism — the
155project-root `.design-dna/` store, the marker-first `active` selector, the slug
156grammar, schema validation with "not observed" backfill on load, and the
157confirm-before-overwrite / verify-by-re-read save path. A project with no
158profile marker proceeds exactly as above; persistence adds a save hook and a
159start-from option, never a routing change.
160
161## Delivery gate
162
163Verify before handing over. Each item below has failed in practice.
164
165- Every colour in the output traces to a DNA palette entry.
166- Font families, spacing rhythm, and radius match their DNA tokens.
167- Body text meets 4.5:1 contrast, large text 3:1.
168- `prefers-reduced-motion: reduce` is honoured — not merely detected.
169- Nothing renders for an effect whose `enabled` flag is `false`.
170- Animation loops use `requestAnimationFrame`; `setInterval` is not an
171 animation primitive and drifts against the display refresh.
172- Canvas and WebGL contexts are sized to their container and handle resize.
173- The declared `fallback_strategy` is actually implemented, not just recorded.
174
175## Polish iteration
176
177A first pass that reads thin is usually not a token problem — it is an
178attention problem, and re-reading the reference beats re-reading the output.
179Re-attach the same references and audit against them along six axes:
180hierarchy, ornamentation, typographic rhythm, motion, materiality, and overall
181interface finish. Merge the conclusions back into the current implementation
182rather than regenerating from scratch, which discards the parts that were
183already right.
184
185## Boundaries
186
187| Request | Owner |
188|---|---|
189| Markdown report → HTML | `moai-domain-html-report` |
190| Architecture / flow diagram | `moai-domain-svg-infographic` |
191| Chart, dashboard, or categorical palette | `dataviz` |
192| Component-level finish: concentric radius, optical alignment, hit areas, easing craft | `moai-ref-ui-polish` |
193| Hosted claude.ai visual-identity page | `artifact-design` |
194| Design-system sync with the Claude Design product | `manager-design` |
195
196This skill owns one thing the others do not: turning an **existing reference**
197into a structured profile, and generating from that profile. Where the design
198is authored from first principles rather than deconstructed, those skills own
199it.
200
201## References
202
203- `references/dna-schema.md` — the three-dimension field list and enum vocabularies
204- `references/diagram-profiles.md` — named-profile persistence: the `.design-dna/` store, marker-first resolution, slug grammar, load-time validation
205- `references/effects-implementation.md` — performance tiers, technology selection, and per-effect implementation patterns