playbooks

home / skills / derklinke / codex-config / design-system-doc

design-system-doc skill

/skills/design-system-doc

This skill keeps the DESIGN.md as the authoritative, cross-platform design system source of truth, aligning tokens, typography, spacing, and component rules.

npx playbooks add skill derklinke/codex-config --skill design-system-doc

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.6 KB
---
name: design-system-doc
description: Maintain and enforce a repo-root DESIGN.md as living, platform-agnostic design system documentation. Use for UI/design implementation or review tasks across web and Apple platforms (iOS/macOS) to keep tokens and component rules consistent with current state.
metadata:
  short-description: Current-state DESIGN.md governance
---

# Design System Doc

Use this skill whenever work touches UI, visual design, theming, motion, layout, component variants, or brand expression on any platform.

## Objective

Keep `<repo-root>/DESIGN.md` as the operational single source of truth for current design system constraints across platforms.

## Required Workflow

1. Resolve repository root and open `DESIGN.md`.
2. If missing: create from `references/design-template.md`, then tailor to project context.
3. Read current constraints before editing UI code: tokens, typography, spacing/radius, motion, component rules, vibe, and platform mappings.
4. Implement changes with strict adherence to documented tokens/components.
5. If divergence is required, update the system spec directly (current state), and prefer system-level updates over one-off overrides.
6. Update `DESIGN.md` in the same task:
   - changed tokens/styles/components
   - per-platform mappings (`web`, `ios`, optional `macos`)
   - affected screens/surfaces (current coverage)
   - remove/replace stale statements so file reflects only what is true now
7. In delivery notes, reference what was enforced and what was updated in `DESIGN.md`.

## Enforcement Rules

- Avoid introducing raw color/spacing/typography values when tokens exist.
- Avoid undocumented component variants, states, or interaction patterns.
- Preserve established style/vibe unless user requests a rebrand.
- Record accessibility implications per platform (e.g., WCAG contrast/focus for web, Dynamic Type/VoiceOver/reduced motion for iOS).
- Require explicit mapping for each core token/component to target platform implementations (e.g., CSS vars/classes, SwiftUI `Color`/`Font`/tokens).
- Keep `DESIGN.md` concise and scannable; favor tables/checklists over long prose.
- `DESIGN.md` is present-state authoritative spec: no changelog, no decision log, no historical timeline.

## File Convention

- Canonical path: `<repo-root>/DESIGN.md`
- Bootstrap source: `references/design-template.md`
- Keep section names stable to preserve diff readability over time.
- If a platform is not in scope, mark mapping as `N/A` rather than removing structure.

## Output Contract

- For implementation tasks: deliver code changes + `DESIGN.md` updates together.
- For review tasks: deliver findings + concrete `DESIGN.md` patch suggestions.

Overview

This skill maintains and enforces a repo-root DESIGN.md as the living, platform-agnostic design system spec. It ensures tokens, component rules, and platform mappings stay current and authoritative for UI work across web, iOS, and macOS. Use it to coordinate implementation and reviews so visual, motion, and accessibility constraints are consistent and actionable.

How this skill works

The skill opens or bootstraps <repo-root>/DESIGN.md from a template, reads the current constraints, and requires updates whenever UI-affecting changes are made. It enforces token usage, platform mappings, and accessibility notes, and mandates delivering code changes alongside the corresponding DESIGN.md edits or review patches. It treats DESIGN.md as the present-state spec — concise, scannable, and the single source of truth.

When to use it

  • Implementing or changing UI, theming, tokens, motion, or layout
  • Reviewing UI PRs for token/variant compliance across platforms
  • Adding or changing component variants, states, or interactions
  • Mapping design tokens to web (CSS) and Apple (SwiftUI) implementations
  • Preparing delivery notes that must document enforced/updated design rules

Best practices

  • Always check DESIGN.md before editing UI to avoid one-off overrides
  • Prefer updating the spec over ad-hoc exceptions; record required changes in the same task
  • Never introduce raw values where tokens exist; map tokens to platform implementations
  • Keep DESIGN.md concise: use tables, checklists, and stable section names for diff readability
  • Include accessibility implications per platform (WCAG, Dynamic Type, VoiceOver, reduced motion)

Example use cases

  • A developer implements a new button variant: update tokens, add platform mapping, and ship code + DESIGN.md changes together
  • A reviewer flags a PR using raw hex colors; provide a DESIGN.md patch suggesting token usage and mappings
  • Introducing a new spacing scale: add token definitions, map to CSS vars and SwiftUI tokens, and mark affected screens
  • Reducing motion: document reduced-motion behavior per platform and add accessibility notes to DESIGN.md
  • Onboarding a designer: bootstrap DESIGN.md from template and tailor constraints to project context

FAQ

What if DESIGN.md is missing?

Create it from the design-template reference, tailor content to the project, and commit before UI changes.

Can I keep a changelog or decision history in DESIGN.md?

No — DESIGN.md is the present-state authoritative spec. Keep change logs elsewhere; remove stale statements from the file.

How do I handle a platform out of scope?

Mark that platform mapping as N/A in DESIGN.md rather than removing the structure to preserve consistency.