agentleFS
finograficfinografic/ai-agent-config/.agents/skills/apply-design-md/SKILL.md

apply-design-md

Skill0 starsChanged 3 months agoMITView on GitHub

Enforce a project's DESIGN.md across its UI codebase. Crawls the route tree, audits pages/components against the DESIGN.md tokens and rules, fixes ONLY misaligned code, and writes a final alignment report to .agents/. Success = uniform, consistent shared design language across all pages.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    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:

    Respect the source of truth: Read the ## Source of Truth section of DESIGN.md.

    line 16
  2. Very specific:

    Read DESIGN.md (root, or .stitch/DESIGN.md).

    line 25
  3. Very specific:

    Do's and Don'ts, layout/elevation/shape principles.

    line 43
  4. Distinctive:

    Never: change copy/content, alter layout structure beyond the cited rule, rename things, reformat untouched lines, or "fix" a page that had …

    line 101
  5. Distinctive:

    Run the project's own checks (typecheck / lint / build.

    line 107
  6. Distinctive:

    If the project runs locally, spot-check 2–3 changed routes in the browser for regressions.

    line 108

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

Apply DESIGN.md — Align the Codebase to the Design System

DESIGN.md states the rules; this skill makes the code obey them. It audits every route, touches only what is misaligned, and leaves a full audit trail in .agents/.

Prime directives:

  • Minimal diff. A page already aligned is not edited, not reformatted, not "improved".
  • Respect the source of truth. Read the ## Source of Truth section of DESIGN.md. If a design system (PandaCSS, Tailwind theme, @finografic/design-system) is canonical, fix code by pointing it at existing DS tokens/recipes — never by hardcoding literal values. Only when DESIGN.md itself is canonical may literals be normalized directly to its token values.
  • Don't redesign. Alignment means conforming to DESIGN.md, not personal taste. A rule not present in DESIGN.md is not enforceable.

Step 1 — Load and validate DESIGN.md

Read DESIGN.md (root, or .stitch/DESIGN.md). Resolve every token reference. Validate first:

pnpm dlx @finografic/genx design lint

(wraps the official @google/design.md linter). If lint reports errors, stop and surface them — never enforce a broken spec. When a design system is canonical, also run pnpm dlx @finografic/genx design check: if the mirror has drifted, refresh with genx design sync --pull before enforcing stale tokens on the codebase. Also load .agents/design/DESIGN_DEVIATIONS.md if present (produced by generate-design-md): it is a pre-computed work-list of known misalignments.

Build the rule set to enforce:

  • Tokens (frontmatter): exact colors, typography objects, spacing scale, radii, component property values.
  • Prose rules (body): usage constraints ("primary only for the most important action"), Do's and Don'ts, layout/elevation/shape principles.

Step 2 — Crawl the route tree

Framework-aware route discovery:

FrameworkRoutes
Next.js (app router)app/**/page.{tsx,jsx,mdx} + layout.*
Next.js (pages)pages/**/*.{tsx,jsx}
React Router / TanStackroute config or routes/** file convention
Astrosrc/pages/**
SvelteKitsrc/routes/**/+page.svelte
Vue/Nuxtpages/**

For each route, build its implementation closure: the page file, its layout(s), and the local components it imports (follow imports one or two levels — shared UI primitives matter most; skip node_modules except to note which DS components are used). Emit a route → files map.

Step 3 — Audit each route (classify, don't fix yet)

Compare the closure of each route against the rule set. Record findings as:

route | file:line | category | severity | found | expected (token) | rule source

Categories: color · typography · spacing · radius · elevation · component · layout · dos-donts · a11y.

What counts as misaligned:

  • Literal values that differ from the corresponding token (a raw #1B1D20 where colors.primary = #1A1C1E; a border-radius: 6px where the scale has 4/8).
  • Values off the spacing scale (17px padding in an 8-based system).
  • Wrong token for the semantic role (secondary color used on a primary CTA).
  • Component implementations contradicting components tokens (button padding, radius, bg/text colors) or the prose component conventions.
  • Violations of explicit Do's and Don'ts (mixed corner language in one view, >2 font weights on a screen, contrast below the stated floor).
  • Equivalence, not textual identity: rgb(26,28,30) ≡ #1A1C1E; a Tailwind class or Panda token that resolves to the expected value is ALIGNED — leave it alone.

Skip routes with zero findings — list them as aligned and never touch them.

Step 4 — Fix misaligned routes only

Order fixes by blast radius: shared components first (fixing one button component may clear findings on many routes), then per-route files.

Per finding, choose the smallest conforming change, in this preference order:

  1. Use the design system. Swap the literal/ad-hoc style for the existing DS token, utility class, or recipe (text-primary, token(colors.primary), DS <Button variant="primary">).
  2. Normalize the literal to the DESIGN.md token value — only when no DS is canonical.
  3. Structural conformance (component markup/variant changes) — only when required by an explicit component rule, and keep behavior identical.

Never: change copy/content, alter layout structure beyond the cited rule, rename things, reformat untouched lines, or "fix" a page that had no findings.

Step 5 — Verify

  • Re-scan the changed files: previous findings must now resolve to aligned.
  • Run the project's own checks (typecheck / lint / build; visual tests if present).
  • If the project runs locally, spot-check 2–3 changed routes in the browser for regressions.

Step 6 — Final report (required)

Write .agents/reports/DESIGN_ALIGNMENT_<YYYY-MM-DD>.md:

# Design Alignment Report — <date>

**DESIGN.md**: <path> (lint: 0 errors / N warnings)
**Routes audited**: N · **aligned untouched**: N · **fixed**: N

## Changes by route

### /settings
| File | Category | Rule | Before | After |
| ---- | -------- | ---- | ------ | ----- |
| src/routes/settings/page.tsx:88 | color | colors.primary | #1B1D20 | token(colors.primary) |

## Already aligned (untouched)
/, /about, ...

## Not auto-fixed (needs human decision)
| Route | Finding | Why deferred |

## Verification
typecheck ✓ · build ✓ · visual spot-check: /settings, /billing ✓

Findings that are ambiguous, content-coupled, or risky (e.g. a rule conflict inside DESIGN.md itself) go to Not auto-fixed with a reason — deferring is better than guessing. Finish by summarizing the report path and headline numbers to the user.

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.