agentleFS
simscalsimscal/sapiens-dtj/.claude/skills/design-theme/SKILL.md

design-theme

Skill0 starsChanged 4 months agoMITView on GitHub

Use when creating, amending, or editing `DESIGN_THEME.md`. Owns the design-theme document — the binding, concrete design system consumed by the ui-design agent — Design Principles, Color Tokens, Typography, Spacing & Shape, Core Components, Layout Patterns, Imagery & Iconography, States & Feedback, Applying This System to New Pages.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. kensaurus/cursor-kenji★ 9same name
    2. kensaurus/skills★ 9same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository8 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After three failed follow-ups, offer to mark the section Not yet defined rather than write something vague.

    line 66
  2. Distinctive:

    Create asks each verbatim.

    line 161
  3. Distinctive:

    Never invent content — every value/component comes from interview answers, a supplied reference, or confirmed clone research.

    line 188
  4. Very specific:

    Never write placeholder braces ({...}) or "TBD" into the final file.

    line 189
  5. Very specific:

    Never silently overwrite an existing DESIGN_THEME.md — always confirm.

    line 190

≈ “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

DESIGN_THEME.md Authoring

DESIGN_THEME.md = concrete design system, not a mood board — real token values (hex, px), a named type scale, a catalog of reusable components. Opinionated: a reviewer can call any surface on-theme or off. Theme is the source of truth for values — never scan a codebase.

Stack-agnostic — describe components by anatomy, variants, reuse; never by framework, library, or file path.

Mode Detection

DESIGN_THEME.md present?Intent verb in the requestMode
nocreate / set up / generate / init / draftCreate
yescreate / generate / regenerateConfirm: Skip (default) or Regenerate
yesrewrite / overhaul / start overConfirm: Skip (default) or Overwrite
yesamend / update / change / edit / reviseAmend
yesread-only ("what's our accent?", "show the component catalog")Summarise; do not modify

Create

Confirm DESIGN_THEME.md absent (or Regenerate/Overwrite chosen). Then:

  1. Source selection — ask via AskUserQuestion → $SOURCE:
    • From a reference screen — user supplies one or more screenshots / a link to a designed surface; derive the whole system from it (principles, tokens, type, components).
    • Clone from existing product(s) — user names 1–3 reference products (e.g. Linear, Stripe, DoorDash), optionally which aspects to take from each.
    • From scratch — interview only, no seeding.
  2. Reference/clone research — reference screen → read it directly and extract concrete values (dominant accent, ink levels, radii, type weights, the repeating component shapes). Clone → per product, research its design language via WebSearch / WebFetch (design-system docs, brand guidelines, teardowns). Draft every section as concrete values + named components, not adjectives.
  3. Interview — one AskUserQuestion per section in canonical order, seeded per $SOURCE ("derived from the reference: … — confirm / edit" or Question Bank verbatim). Apply Specificity Tests with follow-ups.
  4. Consistency pass — resolve contradictions across sections (principles vs token usage vs component variants vs states); multiple sources → resolve clashes explicitly with the user.
  5. Write DESIGN_THEME.md at the repo root per File Structure. Header = # {Product} Design System + a one-line italic design-intent subtitle; when derived, fold the provenance into that subtitle (derived from the meal-detail reference screen).
  6. Confirm — path + one-line summary per section.

Amend

Read DESIGN_THEME.md (absent → stop: No `DESIGN_THEME.md` found. Create it first.). Capture the full baseline verbatim — every section, subtitle, non-canonical content; non-targeted sections preserved byte-for-byte. Determine target section(s) from the arg via Section Argument Map, else ask which. Accept free-text deltas (e.g. a forwarded divergence report from the ui-design agent). Offer cascade revisits (not forced):

  • Design Principles → Color Tokens, Core Components, States & Feedback
  • Color Tokens → States & Feedback, Core Components
  • Spacing & Shape → Core Components, Layout Patterns
  • Core Components → Layout Patterns, Applying This System to New Pages

Interview targeted section(s) → Specificity Tests → consistency pass against untouched baseline → rewrite per Apply Rules → overwrite DESIGN_THEME.md → confirm section(s) updated.

Specificity Tests

Apply after every interview answer; on failure ask a focused follow-up.

General (all sections): could an AI designer who has never seen the app produce a surface a reviewer recognizes as on-theme? Every rule must be checkable — a reviewer can point at a screen and say pass/fail. Concrete over adjectival: a value, a threshold, or a named component beats a mood word.

SectionTest
Design PrinciplesEach principle has a memorable name + an app-wide rule that discriminates. "Clean and modern" fails; "Appetite-first: photography wins the hierarchy, chrome stays neutral" passes.
Color TokensEvery token has a concrete value + a bounded usage, plus one rule capping the accent. "Use brand colors tastefully" fails; "accent-primary #E8352F on price + final CTA only; one loudest red per screen" passes.
TypographyNamed family + a scale mapping each style → size/weight/tracking/usage. "Clear hierarchy" fails; "Display 32–40 Bold for dish names; Price 15–16 Bold always accent" passes.
Spacing & ShapeBase grid unit + radius scale + a rule giving each border style a meaning + an elevation stance. "Breathing room" fails; "8px grid; card radius 20–24; dashed border = optional only; single soft shadow on floating panels" passes.
Core ComponentsEach named component states anatomy + variant states + an explicit reuse list. "Nice buttons" fails; "Segmented Choice: pill row, single-select, active = black fill; reused for size / spice / time-slot / payment" passes.
Layout PatternsThe app-wide grid + desktop zone split + section-header pattern + mobile collapse rule. "Responsive" fails; "desktop two-zone 65–70 / 30–35 persistent panel; mobile → bottom sheet" passes.
Imagery & IconographyPhotography direction + an icon spec (stroke, caps, size). "Nice photos" fails; "top-down natural light, circular plate, no busy backgrounds; icons 1.5px thin-line rounded caps, 20px nav" passes.
States & FeedbackHover / selected / disabled deltas + semantic color rules for values. "Good feedback" fails; "hover darken 8%; selected = black fill; discounts red --prefixed; free = green, never red" passes.
Applying This System to New PagesA decision checklist mapping screen questions → which components to reuse. "Stay consistent" fails; a numbered "browsing list → chips + card rows" checklist passes.

After three failed follow-ups, offer to mark the section Not yet defined rather than write something vague.

Contract

File Structure

Pure markdown — no frontmatter, no version field. Header is # {Product} Design System followed by a one-line italic design-intent subtitle. Nine canonical sections in immutable order, numbered as below:

# {Product} Design System
*{one-line design language intent; when derived, name the reference here}*

---

## 1. Design Principles

{4–6 named principles, each a bolded name + an app-wide rule — e.g. "**Appetite-first**: photography wins the hierarchy, chrome stays neutral"}

---

## 2. Color Tokens

| Token | Hex (approx) | Usage |
|---|---|---|
{every semantic token → concrete value → bounded usage — canvas, surface, subtle, accent + hover, ink primary/secondary/tertiary, borders, success, inverse}

**Rule of thumb:** {one sentence capping the accent — e.g. only one loudest red per screen}

---

## 3. Typography

**Family:** {named family or class}

| Style | Size | Weight | Tracking | Usage |
|---|---|---|---|---|
{Display, H2, Label/Eyebrow, Body, Meta, Price, Button Label → size range, weight, tracking, usage}

---

## 4. Spacing & Shape

{bullets: base grid unit; card + pill radius scale; thumbnail crop rule; border-weight rule giving dashed/solid distinct meaning; elevation stance (one soft shadow, floating panels only) + layering order}

---

## 5. Core Components

{one `###` sub-block per reusable component — Navigation Tabs, Filter Chips, Segmented Choice, Icon Toggle Grid, Quantity Stepper, contextual Primary CTA, Final CTA, List Row, Recommendation Card, Summary Panel, Promo/Tag Pill. Each: anatomy + variant states + explicit reuse list.}

---

## 6. Layout Patterns

{bullets: top-nav-bar composition; desktop main/side zone split with ratios; section-header pattern; mobile collapse rule}

---

## 7. Imagery & Iconography

{photography direction; icon spec — stroke, caps, monochrome, sizes}

---

## 8. States & Feedback

{hover / selected / disabled deltas; semantic value rules — discount/negative, free/positive; motion stance — duration/easing, what animates, what never, reduced-motion}

---

## 9. Applying This System to New Pages

{numbered decision checklist: screen question → components to reuse; final rule pinning the single red final action}

Optional bottom sections, only when defined: ## Accessibility Baseline (only when exceeding the WCAG AA default). Non-canonical user-added sections appear at the bottom and are preserved untouched on amend.

Section Argument Map

ArgumentSection
principlesDesign Principles
color, colors, or tokensColor Tokens
typography or typeTypography
spacing or shapeSpacing & Shape
componentsCore Components
layoutLayout Patterns
imagery, icons, or iconographyImagery & Iconography
states or feedbackStates & Feedback
applying or new-pagesApplying This System to New Pages
allAll sections
Comma-separated list (e.g. color,components)Multiple sections

Interview Question Bank

Create asks each verbatim; Amend prefixes "the updated" or "now" where natural. Reference/clone seeds each with the drafted content instead.

SectionQuestion
Design Principles"What 4–6 named principles govern the whole app? Each = a memorable name + one app-wide rule (e.g. 'Appetite-first: photography wins the hierarchy')."
Color Tokens"What are the color tokens? Per token: a concrete value and a bounded usage. What single rule caps the accent color?"
Typography"What type family, and what's the scale? Map each style (Display, H2, Eyebrow, Body, Meta, Price, Button) to size, weight, tracking, usage."
Spacing & Shape"What's the base grid unit and radius scale? What does each border style mean, and what's the elevation stance?"
Core Components"What are the reusable components? Per component: anatomy, variant states, and the list of surfaces that reuse it."
Layout Patterns"What's the app-wide grid? Top-nav composition, desktop main/side zone split with ratios, section-header pattern, mobile collapse rule."
Imagery & Iconography"What's the photography direction and the icon spec (stroke, caps, monochrome, sizes)?"
States & Feedback"What are the hover / selected / disabled deltas, the value color rules (discount, free), and the motion stance?"
Applying This System to New Pages"Give the decision checklist a designer runs for a new screen — screen question → components to reuse — ending with the single-red-final-action rule."

Apply Rules

  • Create writes the file end-to-end via File Structure. Every section gets concrete content — no placeholders, {…} braces, "TBD".
  • Amend edits only targeted section(s); non-targeted sections preserved byte-for-byte (headings, tables, bullets, subtitle, bottom non-canonical sections). Target all → rewrite all nine canonical sections, preserve non-canonical. Single section → rewrite only its body, leave heading + number unchanged.
  • Specificity Test failing after three follow-ups + user agrees → write Not yet defined. as the section body.

Constraints

  • Section order is immutable — nine numbered sections in the File Structure order.
  • Section headings match canonical names (and numbers) exactly.
  • Color Tokens and Typography and Spacing carry concrete values (hex, px ranges, grid units); Core Components and States reference tokens by semantic name (accent-primary, ink-secondary), never re-spell the hex.
  • Zero stack coupling — no framework, library, or file-path assumptions; components are described by anatomy + behavior, never implementation.
  • DESIGN_THEME.md is pure markdown — no YAML frontmatter, version field, or metadata block.
  • Never invent content — every value/component comes from interview answers, a supplied reference, or confirmed clone research.
  • Never write placeholder braces ({...}) or "TBD" into the final file.
  • Never silently overwrite an existing DESIGN_THEME.md — always confirm.
  • Filesystem: write only DESIGN_THEME.md.

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.