create-design-md

Files (1)

• SKILL.md

SKILL.md (first lines)

# Create DESIGN.md

Create a `DESIGN.md` for one product or coherent website. Record the design language that governs it, not every value that happens to exist.

## Boundaries

- Modify only `DESIGN.md`. Do not change product source, dependencies, configuration, or generated files.
- Use the DESIGN.md format contract below. Do not invent a competing schema.
- Do not copy every discovered token or component into the document.
- Do not convert repetition, local styling, or visual preference into product intent.

## 1. Choose the mode

### Repository mode

Use when a local product repository is available. Create or update `DESIGN.md` at the root of the selected product.

If the repository contains multiple deployable products, select the one named by the user. If the request does not identify one and ownership is ambiguous, ask before writing.

Repository evidence may establish normative values, token names, component ownership, and documented rationale.

### URL mode

Use when the user provides a public URL without its source repository. Create a reconstructed `DESIGN.md` draft in the current workspace.

URL mode requires rendered browser access. Inspect the DOM, computed styles, and publicly loaded stylesheets at desktop and mobile widths. Screenshots may support interpretation but cannot establish exact values by themselves.

Inspect the supplied page and shared chrome. For a site-wide request, sample up to three same-origin pages that represent distinct templates.

URL evidence may establish only observable visual patterns and computed values. It cannot establish internal token names, component ownership, undocumented rationale, or whether a pattern is intentionally canonical.

If rendered inspection is unavailable, ask for screenshots or source files. Do not create a DESIGN.md from copy, metadata, or HTML structure alone.

Choose repository mode whenever source is available. A supplied URL may verify rendered presentation but does not replace repository evidence.

## Shared evidence pipeline

The modes differ only in how they collect evidence. They must use the same record and output pipeline:

```text
role → value → source → scope → recurrence → confidence
```

1. Collect evidence using the selected mode.
2. Record the source, scope, and recurrence for each candidate.
3. Normalize candidates into the DESIGN.md schema.
4. Omit candidates that are uncertain, local without a contract, or not implementation-relevant.
5. Validate frontmatter shape and export compatibility.
6. Write Markdown only after the normalized frontmatter passes.

Never let repository or URL evidence introduce a second token schema. The same flat token names, mapping-shaped typography, omission rules, and export gates apply to both modes.

The generated document is private until validation passes. Never return, display, or summarize a DESIGN.md draft before lint and export succeed. If validation reports an invalid shape or missing export category, rewrite the frontmatter and rerun; if the category cannot be repaired, remove it and report it as omitted.

## 2. Trace the evidence

In repository mode, inspect in this order:

1. Existing `DESIGN.md` and explicit repository guidance
2. Tokens, themes, variables, and global styles
3. Shared primitives and their variants
4. Representative routes and rendered consumers
5. Surface-local implementations

A source participates only when the selected product imports, references, inherits, or renders it. Exclude proposals, migrations, examples, generated outputs, legacy implementations, and similarly named packages unless the selected product uses them.

In URL mode, sample representative elements for:

- colors and surface roles
- typography roles
- spacing and layout
- borders, radii, and elevation
- navigation, buttons, inputs, cards, and repeated content structures
- desktop and mobile presentation

Prefer computed values and loaded CSS declarations over visual estimation.

Before drafting URL-mode prose or YAML, build a private evidence ledger for each sampled page and viewport. For each candidate, record: page, viewport, element role, computed property/value, and the matching loaded-CSS declaration or custom property when available. Inspect the public stylesheets loaded by the page, including custom properties and media-query rules; a stylesheet value is usable only when it is connected to a rendered element or recurs across the sampled pages.

Promote a URL value into DESIGN.md when either (a) the rendered computed value and a loaded declaration/custom property agree, or (b) the same computed value recurs for the same role across the required samples. If neither condition holds, omit the value. You may preserve an exposed custom-property name only when its declaration and rendered use are directly observable; do not invent semantic aliases from a raw value.

For every URL-mode claim, require all three proofs before writing it:

1. Observation: the pattern or value is visible or computed on the rendered page.
2. Basis: it is measured, or recurs across the required sampled pages/viewports.
3. Consequence: it changes a concrete implementation choice in DESIGN.md.

If any proof is missing, omit the claim. Do not turn a visual impression into a token, a single occurrence into a site-wide rule, or a guessed value into YAML. Exact values require computed styles or loaded CSS; otherwise describe the role without a value or omit it.

## 3. Decide what belongs

In repository mode, find explicit product intent or a design reference before describing product character. In URL mode, do not invent product character; the Overview may state only the site's observable purpose and presentation, and must identify the document as reconstructed.

Write YAML only from named shared tokens and roles in governing sources. Do not turn utility classes, repeated literals, or component values into token scales.

Treat frontmatter shape as a hard gate, not a stylistic choice: a value that is a token group must be a mapping whose children are the schema's fields. Never emit scalar typography entries (`sans: Geist`), arbitrary nested source objects (`font-family: { mono: ... }`), or rounded keys copied from CSS variable names (`radius-sm`, `radius-md`, etc.).

Use mappings, never sequences, for token groups. When a governing source defines one group-level token such as `--radius`, normalize it to `base`; otherwise preserve the source token names.

Map source values into DESIGN.md schema fields. Preserve semantic token names, not source object nesting. For example, write `typography.mono.fontFamily: Geist Mono`, never `typography.mono: Geist Mono`; write `rounded.base: 0.625rem` when the source has only `--radius`, never `rounded.radius` or derived radius steps.

Resolve framework utilities through the active theme or configuration before writing exact values.

Identify the repository's export target before writing frontmatter: `css-tailwind` for Tailwind v4, `json-tailwind` for Tailwind v3, and `dtcg` otherwise. Token names must be valid for that target.

Check the installed DESIGN.md specification before encoding theme modes:

```bash
npx @google/design.md spec
```

If the specification supports `themes` and `default-theme`, use its theme-aware token syntax. Otherwise, put the default-theme value under each canonical semantic token and preserve exact alternate-theme values in a `## Themes` table. Do not create parallel `-light` and `-dark` token names, discard alternate-theme values, or use unreleased syntax. A fallback Themes table is documentation only; do not pretend it makes the frontmatter theme-aware.

In repository mode, every prose rule must be supported by explicit guidance, a named shared token or variant, or a shared owner used by at least two audited surfaces. Otherwise omit it.

In URL mode, every prose rule must be directly observable. A site-wide rule must recur across at least two sampled templates; otherwise scope it to the inspected page. Use reconstructed role-based names and label the document as a draft.

URL-mode YAML is intentionally sparse, but not empty when measured evidence exists. Add a category when at least one supported value or role survives the three-proof gate. Colors may use computed values or verified public custom properties, but must remain flat and export-safe; typography must use canonical fields such as `fontFamily`, `fontSize`, `lineHeight`, and `fontWeight`; rounded and spacing values must come from computed styles or loaded declarations. Do not create aliases such as `primary`, `elevated`, or `display` merely to organize observations. A component section requires the same interaction or surface treatment to recur across at least two sampled pages and to change a concrete implementation choice.

From ibelick/ui-skills, MIT.

More from ibelick/ui-skills