Use this when you are starting a website or app and want a visual system that is specific to this subject, accessible, and fast to build against. It is for founding a system, not documenting one that exists. The output is not a document. It is a set of tokens, a living styleguide route rendered from the running CSS, and a check that fails the build when someone leaves the system.
The trap this skill exists to avoid: a style guide assembled from a primary colour and a modular scale is a WordPress template with better typography. It will be generically competent and belong to nobody. Everything below is arranged to prevent that.
Related skills: Feeds
/component-specand/interaction-pattern-libraryonce the foundations are set. Use/design-system-auditand/design-system-governancewhen a system already exists and needs assessment or an operating model./brand-guidelines-generatoris the wider brand book; this is the build-facing subset.
Process
Step 1: Find the evidence, do not ask for a primary colour
Never open with "what are your brand colours". Ask instead what already exists that is true to this subject, and derive the palette from it:
- Photography they already own. Sample hexes from real images and name the source of each one. "Monarch orange, from monarch wings and ladybugs in her own grid" survives a client review. "Primary 500" does not.
- The subject's own vocabulary. A product with real domain words gets colours and component names from those words, not from generic UI nouns.
- Their existing layout habits. If they already set type in a block on a photo, that device becomes a component rather than something you invent.
- The trade itself. What the work is physically made of is usually the best texture brief available.
Ask for the logo, the wordmark and any existing marks by name, before sampling anything. A sweep that reads someone's social grid and never asks "what is your logo" has skipped the asset every other decision must live with, and a palette built around a mark nobody looked at will be internally consistent and still wrong. This is not hypothetical: it happened on the worked example in examples.md.
When an existing mark contradicts a rule you were about to write, put it to the client rather than designing around it: does the mark stay, or is it in play? That answer changes the system and only they can give it.
If there is no evidence, say so plainly and go get some before designing. Designing first and justifying after is how a system ends up arbitrary.
Output of this step: every colour has a name, a hex, a named source, and one stated job.
Step 2: Write the ruled-out list before you design anything
Name the category cliche and forbid it in writing. For a garden brand that is muted sage and cream. For a fintech it is navy and a stock photo of a handshake. A system is as much what it refuses, and the refusals are what make every later decision decidable rather than a matter of taste.
Keep it as data, not prose, so the styleguide page can render it. Six to ten entries.
Step 3: Tier the tokens
Two tiers, always. Tier 1 is the raw palette named by hue. Tier 2 is everything the app consumes, and its value is always a tier 1 reference.
Never reference a tier 1 value outside the :root block. That single rule is why a palette change is one block instead of a two hundred file sweep. Detail and worked examples in reference/method.md.
Step 4: Ration the loud colour and measure the contrast for real
Give the loudest colour a small number of named jobs and forbid it everywhere else. If red means "danger" in general, it stops meaning the one thing you needed it to mean.
Measure contrast on composited pixels, not CSS values. A texture, an overlay, or a mix-blend-mode changes the ground under the type, so the declared hex is not what the eye receives. The measuring script is in reference/enforcement.md. Label any colour that passes only at display size as display-only, in the guide itself, next to the swatch.
Step 5: Type as presets, never as settings at the call site
Name three to five type presets by job (.type-ceremony, .type-data, .type-voice). Hand-written font-variation-settings or one-off tracking at a call site always drifts. If a face is doing more than one job, that is fine, but each job gets a preset.
Step 6: Specify texture, ornament and motion
The part standard style guides omit entirely, and the part that separates a considered site from a competent one.
- Texture: what every ground is made of. Flat fill is a choice, not a default, and it should be a stated one.
- Ornament: name the classes for what they do, not what they depict (
.ornament-corners, not.ornament-vine). Motif-neutral names mean changing the art direction is not a rename across every consumer. - Motion: what moves, how far, how long, and why. Every animation needs a
prefers-reduced-motionpath, including the ones a class-name guard cannot see because they ship with the framework. - The cheesy guard: for each of the three, write the specific failure mode and the one rule that prevents it. "Growth enters from exactly one edge per section and must be cropped" is a rule. "Keep it tasteful" is not.
Step 7: Build the living page, not a document
A Markdown style guide drifts from the code within a week. Build a route that renders from the running CSS so it cannot lie: swatches from the tokens, the type presets set in real type, the ornaments, the motion, and a contrast grid covering every ink and surface pair. Section list in reference/enforcement.md.
Keep it out of production (a dev-only route, or clearly marked as a draft for review).
Step 8: Make the system enforceable
A guide nobody can violate is a system. A guide nobody enforces is a suggestion. Ship at least a check that fails on raw framework palette classes and on colour literals inside arbitrary values and inline styles. Script in reference/enforcement.md.
Step 9: Review before it hardens
Show the client the living page and ask what feels wrong. Changing a token now is free. Changing it after forty components exist is not.
Output format
Four artefacts, not a document:
- A tokens file with the two tiers and a comment on each tier 1 colour naming its real-world source.
- A brand-as-data file exporting the swatches, the type scale and the ruled-out list, so the styleguide page renders from the same values the app uses.
- A living styleguide route with these sections, numbered: where this came from, palette (with measured contrast per swatch), type, texture and ornament, motion, components, ruled out.
- A check script wired into the build.
If the client needs a shareable document too, generate it from the data file. Never maintain it by hand.
Uncertainty Policy
| Topic | Tolerance | Action |
|---|---|---|
| The evidence base (photos, vocabulary, existing habits) | Low | STOP and ask. Without it the system is arbitrary and this skill has nothing to work from |
| An existing logo or wordmark | Low | STOP and ask, by name, every time. Never record "no logo" without having asked outright |
| Whether an existing mark stays or is in play | Low | STOP and ask. It decides whether the mark constrains the system or the system replaces the mark |
| What the category cliche is | Low | STOP and ask. The ruled-out list is what makes later decisions decidable |
| Accessibility target | Medium | Default to WCAG AA and flag [ASSUMED]. Ask if AAA is needed |
| Specific typefaces | Medium | Recommend a pairing that fits the evidence, flag [ASSUMED], note licence cost |
| Motion appetite | Medium | Default to restrained, one moving thing per viewport, flag [ASSUMED] |
| Framework and token syntax | High | Read the repo and match what is there |
| Dark mode | Medium | Ask. It doubles the contrast work and many marketing sites do not need it |
Default: STOP and ask when a topic is not listed above.
Personalization
On first run, if skills/style-guide/config.md does not exist, ask these setup questions and write the answers there:
- Default stack and token syntax (Tailwind v4
@theme, CSS custom properties, Style Dictionary, something else) - Default accessibility target, and whether dark mode is in scope by default
- Whether to ship the enforcement check and the contrast script every time, or only on request
- House prose rules for anything the guide says in words (em-dashes, spelling, voice)
- Where the living styleguide route should live, and whether it is dev-only
On every later run, read skills/style-guide/config.md and apply it without re-asking. Edit that file directly to change the answers.
A filled config.md is committed, so this skill ships as "fast food": it works out of the box with Kate's defaults. To publish it for someone else to personalize, delete that file and their first run will ask the questions instead.
Related skills
/design-review-- review mockups against the system this produces/ux-audit-- assess an existing product against it/brand-audit-- check consistency once the system is in use
Output location
Write the artefacts into the project repository, not into chat. The living page is the deliverable, and its URL is what you send for review.
Example Output
/style-guide examples
Example: Honey Girl Grows
A regenerative garden designer and beekeeper in Los Angeles. Michelin kitchens, resorts, corporate campuses and homes. Real work, not a hypothetical.
Input
- Evidence available: her Instagram grid (@honeygirlgrows), several years of it, all her own photography. A published brief for crew t-shirts. Two garden designs in Conceptboard. An existing logo, which this evidence sweep missed. See "What this example got wrong" below.
- Target audience: chefs, resort GMs, corporate facilities leads, and homeowners in west LA.
- Stack: Next.js, Tailwind v4
@theme. - Constraint: no photography delivered yet, so the system has to be specified before the images arrive.
What the skill does with that
Step 1, the evidence. The palette is sampled from her grid rather than chosen. Her photographs are loud and saturated, so every swatch carries the thing it came from:
| Name | Hex | Source | Job | On bone |
|---|---|---|---|---|
| Ink | #14120F | the type in her overlays | Body text, dark blocks | 16.4:1 |
| Bone | #F6F2EA | her light overlay blocks | Primary ground | ground |
| Leaf | #17331F | foliage, deep shade | Dark alternating sections | 12.1:1 |
| Monarch | #E4511E | monarch wings, ladybugs, citrus | Primary accent, display only | 3.4:1 |
| Magenta | #D01B63 | roses, centranthus | Secondary accent, body safe | 4.7:1 |
| Borage | #3A4BC8 | borage flowers | Links | 6.2:1 |
| Moss | #3E7C4A | mid-green foliage | Quiet accent, tags | 4.1:1 |
Note what is absent: no nine-step ramp, no primary-500. Seven colours, each
with one job and a real-world source.
Step 2, the ruled-out list. Written before anything was designed: centred-everything layouts, heroes with 200px of vertical padding, script fonts, soft green gradients, rounded corners on every surface, stock photography, headers reading "Our Services", and muted sage-and-cream wellness palettes.
That last one is the whole point. Sage and cream is what a garden brand is supposed to look like, and it would have been a costume over work that is actually loud.
Step 4, rationing and measuring. Monarch is the loudest colour and reaches only 3.4:1, so it is a display colour and the guide says so next to the swatch. Where an accent is needed at body size, magenta and borage both pass.
Measuring composited pixels later caught what CSS values had hidden: bone type on a monarch flood measured 3.8:1, the same constraint in reverse. Body-size type on a flood became ink, and anything smaller sits on a solid block.
Step 6, texture and ornament. Her own t-shirt brief was the only time she had described a visual system out loud, so it became the ornament brief:
botanical line drawings, insects and flora, placed all over. A praying mantis on the side, a ladybug, a butterfly
Seven drawings, one stroke weight, never filled, always currentColor, and each
rendered at true relative scale. The cheesy guards were written alongside them:
a ladybug is 20px because a ladybug is small; growth enters from one edge and is
always cropped, because growth in four corners is a wreath and a wreath is a
wedding invitation.
Step 7 and 9, the living page. Three complete texture directions rendering the same content, so the comparison is fair, each with a thesis, a provenance list, a build cost, a risk rating and its own cheesy guard. Texture cannot be judged from prose, so the deliverable is a page.
Output artefacts
globals.css-- tokens in@theme, each with its source in a commentlib/brand.ts-- swatches, contrast ratios, type scale andRULED_OUTas data/styleguideand/styleguide/directions-- living pages rendered from the running CSS, both marked as unpublished draftsdocs/design/texture-directions.md-- the handoff, including what was not verified
What this example is not
It is not a finished brand book. There is no logo work, no social templates and
no print application here. Those belong to
/brand-guidelines-generator. This is
the build-facing subset: what a developer needs to build the site correctly and
what a check can enforce.
What this example got wrong
The evidence sweep read her Instagram, her t-shirt brief and her garden designs, and recorded "no logo". There is a logo, and it is the most load-bearing asset a brand has: a watercolour wildflower meadow with monarch and swallowtail butterflies and three bees, over a script wordmark, with a serif small-caps tagline reading "Culinary Gardens & Pollinators".
Three of the eight entries the ruled-out list shipped with are contradicted by the brand's own mark:
| Ruled out | What the logo does |
|---|---|
| Script or handwriting fonts | The wordmark is a script |
| Centred-everything layouts | The mark is a centred, symmetrical composition |
| Muted sage-and-cream wellness palettes | Not sage, but soft watercolour rather than the flat saturated colour the palette thesis is built on |
The type system is also short a voice. It ships Archivo and Archivo Narrow, and the logo's tagline is a serif small-caps that belongs to neither.
None of that was a judgement error. It was a missing input, and the skill's own Step 1 exists to prevent exactly this. So:
Ask for the logo, the wordmark and any existing marks by name, in Step 1, before sampling anything. An evidence sweep that reads someone's social grid and never asks "what is your logo" has skipped the one asset every other decision has to live with. A palette derived around a logo nobody looked at will be internally consistent and still wrong.
Where an existing mark contradicts a rule you were about to write, that is a question for the client, not a thing to quietly design around: does the mark stay, or is it in play? The answer changes the system, and only they can give it.
Counter-example: what the old version of this skill produced
For a B2B fintech, given #1B4F8A as a primary, it generated nine tints named
Glacier, Mist, Cornflower, Steel, Navy, Anchor, Admiral, Abyss and Midnight,
then a Major Third type scale and a five-level elevation system.
Nothing in it was wrong. Nothing in it was specific either. No swatch named a source, nothing was ruled out, no texture or motion was specified, the output was a Markdown document that would drift from the code within a week, and nothing could fail a build. Any of the nine names could have been swapped for any other without changing a single decision downstream. That is the test a style guide has to pass: if the values could belong to a different company without anyone noticing, the guide has not done its job.