agentleFS
robritacca-dotcomrobritacca-dotcom/rift-ds/.claude/skills/new-preset/SKILL.md

new-preset

Skill9 starsChanged yesterdayMITView on GitHub

Add a complete theme preset to the system — every lever declared, the generated stylesheet shipped, the AA gate passed. Use when asked to add a theme, a preset, or a new site look.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Add a theme preset so one data-brand attribute delivers the complete look — site-wide and in the shipped package.

    line 13
  2. Distinctive:

    Use this skill when asked to add a theme, a preset, or a new look — phrases like "add a forest theme", "new preset", "give the site a …

    line 17
  3. Very specific:

    Add an entry to THEME_PRESETS in website/src/lib/theme/presets.ts.

    line 27
  4. Very specific:

    Never hand-edit src/tokens/presets/*.css — they are generated.

    line 85
  5. Very specific:

    Never pin SANCTIONED_AA_GAPS to pass the gate without the owner's explicit decision

    line 86

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

new-preset

Add a theme preset so one data-brand attribute delivers the complete look — site-wide and in the shipped package.

When invoked

Use this skill when asked to add a theme, a preset, or a new look — phrases like "add a forest theme", "new preset", "give the site a corporate look".

The governing idea

A preset is a complete theme, not a tint: every lever holds a saved position, and scripts/validate-theme-presets.mjs is the completeness gate that makes "one attribute, full theme" a guarantee rather than a hope. THEME_PRESETS in website/src/lib/theme/presets.ts is the single source; the generated stylesheets in src/tokens/presets/ compile from presetOverrides in that file, and the playground's live preview composes the same lever functions (website/src/lib/theme/theme-overrides.ts) in a memo of its own that mirrors it. Nothing holds the two compositions to each other, so a change to how the levers combine has to be made in both. The playground's theme export is a third consumer of the composer, and scripts/validate-theme-export.mjs holds it to presetOverrides for every preset in both themes, so a new preset is checked there too.

Instructions

1. Declare the preset

Add an entry to THEME_PRESETS in website/src/lib/theme/presets.ts. The ThemePreset type is the checklist — every field it requires is a decision, not a default to skip:

  • brand (and brandDark when one key cannot serve both themes): the action colour. The lever derives the full action family from it, so pick the key with the AA gate in mind (step 3).
  • Neutral tint (tintOn/tintSeed/tintStrength): whether the greys lean toward the brand. The strength is not applied evenly: light mode's surface steps take only a share of it (LIGHT_SURFACE_TINT_RATIO in website/src/lib/theme/theme-overrides.ts owns the rule and the reason), so judge the strength in both themes, never from light mode alone.
  • Shape (radiusScale, pill): the corner language.
  • The feel levers (density, typeScale, motionScale, elevation): 100/100/100/default is a legitimate position, but state it deliberately. motionScale is stored as a percentage of the shipped durations, so a lower number is a faster theme; the playground slider and /foundations/themes show it as speed through motionSpeedPercent, so a stored 80 reads 120% there.
  • Type weight and tracking (displayWeight, headingWeight, bodyWeight, tracking): one weight per tier (the body lever shifts its tier rather than setting it, so emphasis and overline keep their distance above the paragraph) and a letter-spacing offset added to every style's shipped tracking. The SHIPPED_* constants in website/src/lib/theme/theme-overrides.ts are the base look's positions. A single style that should differ from its tier goes in extraOverrides. Keep all three weights inside TYPE_WEIGHT_RANGE (same file) and inside the axis range FAMILIES in scripts/sync-preset-fonts.mjs syncs for the face: the playground previews from a wider Google request than the package ships, so a weight past the synced range previews correctly and ships clamped. Widen the FAMILIES entry and rerun the sync first.
  • Icons (iconWeight, iconFill): the icon font's stroke weight and fill, written to its axis hooks. A heavy text weight usually wants a heavier icon beside it.
  • Tones (logoTone, logoEndTone, displayTone, headingTone, textTone): the colours set apart from the action colour. "action"/"matched"/"ink" keep a role on its usual colour, which is the right position for most themes; a family name tones it, and the composer picks the step per mode that holds the role's contrast (tierToneOverrides in website/src/lib/theme/theme-overrides.ts owns the rule). A role the extras name instead pins its step over the lever, as Signal's display tier does; the extraOverrides JSDoc on ThemePreset in website/src/lib/theme/presets.ts owns that rule. The completeness gate checks the toned roles against the page and the card fill in both themes.
  • Faces (fontLabel, optionally headingFontLabel): the type pairing; the picker previews these, so labels must match FONT_OPTIONS/HEADING_FONT_OPTIONS entries in website/src/lib/theme/theme-overrides.ts byte-exactly (some labels carry a parenthetical that is part of the label, (serif) and (rounded) today; copy the label from the array).
  • accents: the ambient sextet. These feed chart series 2–7 unless extraOverrides re-points the series (a look with grey accents can still chart in colour), and are what the background blobs follow by default, so curate them as one palette around the key. SHIPPED_ACCENTS in website/src/lib/theme/theme-overrides.ts shows the default set's shape.
  • ambient (optional): six hexes for the background blobs alone, in --color-ambient-1 to -6 order, for a look whose field should sit closer to its key colour than its chart palette can. Leave it out and each blob follows its accent. The list is one set for both themes; a blob that needs a different colour in dark mode goes in extraOverridesDark (Smoke is the precedent). design.md's Ambient section owns the token roles.
  • ambientField (optional): "fade" draws the ambient field from the action colour's fade; presetOverrides in presets.ts owns what it sets.
  • aiGradient (optional): "tonal" draws all three AI gradient stops from the action key's ramp; "fade" is the action colour fading toward the page, the rule for an imported theme whose source states no gradient; leave it out to keep the base look's red and blue stops, or leave it out and state all three stops in extraOverrides for a gradient that crosses two tones. design.md's AI section owns when each suits a key colour.
  • advanced ramp rebases and extraOverrides where the derived look needs correcting — the existing presets are the worked examples of when each is warranted (a lifted label for contrast, a re-keyed ramp for harmony, one style stepped off its tier's weight, such as a sub-display a step lighter than the display tier) — plus extraOverridesDark for the roles that cannot hold one value across both themes (the usual repair when the dark cell fails the AA gate in step 3).

An override that moves a fill moves the whole state set. Inverting a button (an ink fill under a coloured label, say) means overriding the resting, hover and pressed fills and the labels that sit on them, --color-action-primary-text and --color-action-primary-text-active. Active icons alias the active label, so they follow without a declaration of their own. Hover and pressed fills should step away from their label: brighter under a dark label, deeper under a light one. That is the rule the lever's derivation follows, and stepping toward the label is how a pressed state drops below AA.

Write its one-line description. Add the id to THEME_TAGLINES in the same file: one sentence on the theme's character (its mood, then the two or three choices that make it, such as the key colour, the faces or the corners), shown under the theme's name on its specimen page. It is shipped copy, so content-design.md applies; scripts/validate-theme-presets.mjs fails the build on a theme without one, on an em dash, or on more than one sentence.

Existing entries in the file are the reference implementations; read two before writing one.

2. Decide where it appears

Add the id to HUE_ORDER (same file) in its curated position — the array's own comment owns the ordering rule, so read it rather than guessing where the entry belongs. THEME_SELECTOR_ORDER is derived from it (the served theme first, then the rest in hue order), and every theme-picking surface walks that list — the home hero's tile row and the header's theme switcher, the playground's preset picker, the theme gallery, get-started's preset list, Storybook's Theme toolbar — so one edit places it everywhere; there is nothing to wire. The theme's specimen page, /foundations/themes/<id>, is generated from the same list (generateStaticParams in website/src/app/foundations/themes/[id]/page.tsx), and the gallery card links to it.

Making it the served theme (the look every visitor gets before choosing one) is a separate decision for the owner. Its one home is SERVED_THEME_ID in website/src/lib/theme/brand.ts: change it there and never restate the id elsewhere, since the root layout and Storybook's preview both read the constant. The selector order leads with the served theme by derivation, so there is no second edit; then run npm run verify.

3. Generate, gate, verify

node scripts/generate-preset-stylesheets.mjs
node scripts/validate-preset-stylesheets.mjs
node scripts/validate-theme-presets.mjs
node scripts/validate-theme-export.mjs
node scripts/generate-theme-design-md.mjs
node scripts/validate-theme-design-md.mjs
node scripts/validate-generated-files.mjs

The generator writes the preset's html[data-brand] stylesheet and refreshes the presets.css aggregate; they ship in the npm package. Downstream generators re-embed the preset CSS too (the shadcn registry's base item among them — scripts/chain.mjs is the authoritative list), so commit every file the chain regenerates, not just the two named here. The completeness gate then holds every override to a real token, primitive or icon axis hook (the script's doc block owns the rule), requires the action family and all six accents, and checks every action fill against what components draw on it, in every state and both themes: labels at WCAG AA 4.5:1, icons and strokes at 3:1. ACTION_PAIRINGS in the script is the authoritative table, and each failure names the fill, the foreground, the ratio and the component that draws it. A failing pairing means the key or an override needs to move (deepen or lighten the key, step a hover or pressed fill away from its label, or lift the label through extraOverrides) — pinning a gap in SANCTIONED_AA_GAPS is deliberate acceptance with a written reason, never a shortcut, and needs the owner's sign-off.

A face the presets have never shipped needs node scripts/sync-preset-fonts.mjs first — a deliberate by-hand fetch, never part of the build; its FAMILIES table is the download spec, and its doc block owns the contract (CLAUDE.md's Fonts entry points there). The stylesheet generator fails naming the script otherwise, and the downloaded woff2s commit with the preset.

The two DESIGN.md lines write and check the theme's own DESIGN.md (website/public/themes/<id>/DESIGN.md), the file the specimen page offers for download: the validator reads it back through the playground's importer and fails when it does not land on the preset's own levers. A difference the format cannot carry goes in that script's SANCTIONED_DRIFT table with the reason; commit the generated file with the preset.

Then npm run verify — the mirror guards and the site build exercise everything those scripts do not.

4. Prove it live

Pick the new theme from the home page's selector and walk a component page, a chart, and the chat surfaces in both light and dark and under each background in the header menu (every scene background reads the preset's --color-ambient-* roles on every page, so the ambient sextet has more than one ground to hold up on), plus a doc page with an h2 over an h3 (or the playground's Type view) when the two tier weights are equal or close, since size is then carrying the hierarchy alone. Then open its specimen page, /foundations/themes/<id>, in both modes: the header, the description, the shader banner and every swatch, type row and control on it are drawn in the theme, so it is the quickest single look at the whole theme, and the hex values on its swatches are the ones the theme actually resolves to. The completeness gate proves resolution; only eyes prove the look holds together.

Then Figma

The Figma kit's variables do not follow on their own. Ask the owner whether to run the figma-tokens skill now or in a separate session, so the kit picks up the change.

Guardrails

  • Never hand-edit src/tokens/presets/*.css — they are generated; scripts/validate-generated-files.mjs rejects a hand edit anyway
  • Never pin SANCTIONED_AA_GAPS to pass the gate without the owner's explicit decision
  • A preset's portrait (swatch shape, faces) derives from its declaration — never restyle a picker row by hand

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.