| name | deepworkplan-addon-design-system |
| description | Optional DeepWorkPlan addon that gives a frontend/UI repo a DESIGN.md (under docs/, indexed from AGENTS.md) — a Markdown design-system file any coding agent reads to generate UI consistent with the repo's OWN design system. Reasons about the repo's ACTUAL design tokens (CSS custom properties, Tailwind config, token files, component styles) rather than copying a brand file; documents colors & roles, typography, spacing/layout, elevation, shapes, components, responsive behavior, do's & don'ts, and an agent prompt guide; checks contrast (WCAG AA) and token integrity. Frontend-scoped and default-on when a UI/design system is detected (applied in trust mode, strongly recommended in guided mode; never offered for backend/CLI/library-only repos); never required for baseline conformance; reconciles an existing DESIGN.md instead of clobbering it. Use when the developer wants agents to produce on-brand, consistent UI for a frontend repo. |
| version | 2.7.0 |
| documentation_url | https://deepworkplan.com |
| user-invocable | true |
| allowed-tools | Bash, Read, Grep, Glob, Edit, Write |
| metadata | {"openclaw":{"emoji":"🎨","homepage":"https://deepworkplan.com"}} |
DeepWorkPlan — Design-System Addon
Give a frontend/UI repo a DESIGN.md — living under docs/ alongside
the repo's other specs and indexed from AGENTS.md — so any human or AI agent
generates UI that matches the repo's own design system, instead of the
unstyled, statistically-common defaults an agent falls back to with no guidance.
This is an opt-in addon — it is never required for a repo to be AI-first,
and it is only for repos with a real UI surface.
The rule that overrides everything: REASON about the repo's tokens, then write
A DESIGN.md is only useful if it reflects this repo. The first job is to
read the repo's real design source — its stylesheet, CSS custom properties,
Tailwind config, token files, and component styles (see SPEC.md §3–§5 and
templates/presets.md) — then document those values. Never paste a
third-party brand's DESIGN.md (a Stripe/Linear/etc. catalog entry) into the
target repo: reference catalogs are inspiration for structure, never content.
Read these first (all relative inside the skill)
SPEC.md — the normative (RFC-2119) contract: frontend-scope gate,
canonical sections, reason-don't-copy, reconcile-don't-clobber, accessibility &
token integrity, pragmatic-reference posture, validation step.templates/DESIGN.md.md — the annotated DESIGN.md
skeleton (each canonical section + how to fill it from the repo). The shape is
fixed; the content is reasoned per repo.templates/presets.md — per-stack reasoning presets
(Tailwind, CSS-variables/vanilla, component-library/design-tokens) — where to
find tokens in each stack. A starting checklist, not an answer key —
detected reality wins.templates/agent_prompt_guide.md — the
"Agent Prompt Guide" block to embed so downstream agents know how to follow
DESIGN.md.templates/design-system-command.md — the
optional /design-system delegator this addon MAY install into the target
repo's .agents/commands/ (only when accepted and wanted).../README.md — the addon mechanism (opt-in, reconcile-don't-clobber, contract).
When this runs
- From
onboard Phase 7b — after the core AI-first scaffolding. This addon is
default-on when detected (SPEC.md §3.1): when a frontend/UI surface is
detected, onboard applies it in trust mode (and strongly recommends it
in guided mode); when no UI surface is detected it is not offered. Either way
the developer may decline and the repo stays baseline-conformant.
- Directly —
/deepworkplan-addon-design-system on an already-onboarded repo
to create or refresh DESIGN.md, or via the installed /design-system
delegator if one was added.
The flow
Step 0 — Consent + frontend-scope gate
- Confirm the developer wants a
DESIGN.md (skip silently if declined — the repo
stays baseline-conformant).
- Confirm the repo has a UI surface (
SPEC.md §3): look for stylesheets / CSS
custom properties, a Tailwind config or @theme block, UI components
(.tsx/.vue/.svelte/.astro), or a token/brand source. If there is no
UI surface, stop and tell the developer this addon does not apply.
Step 1 — Locate the design source (the part you MUST reason about)
Find where this repo's design values actually live, using templates/presets.md:
- Tailwind →
tailwind.config.* or a Tailwind v4 @theme {} block in CSS:
theme colors, font families, spacing, radius, screens.
- CSS variables / vanilla →
:root { --… } custom properties in the global
stylesheet; spacing/size scales; media-query breakpoints.
- Component library / design tokens → a
tokens.* / theme.* export, a
design-tokens JSON, or a Storybook/theme file.
- Brand/style guide → any
BRAND*.md / STYLE*.md doc, plus accessibility
rules documented in AGENTS.md/CLAUDE.md.
A repo MAY combine sources (a Tailwind config + a brand doc + CSS vars). Read all
that exist; the real files win over any preset assumption.
Step 2 — Reason out each canonical section
Using templates/DESIGN.md.md, fill each section from the design source:
Overview/atmosphere · Color palette & roles (light + dark) · Typography · Layout &
spacing · Elevation & depth · Shapes/radius · Components (in terms of the tokens) ·
Responsive behavior · Do's & don'ts (incl. the repo's accessibility rules) · Agent
prompt guide. Express values as named tokens with usage notes; add a
machine-readable token block only if the repo already maintains structured tokens.
Flag any value you had to infer so a human can confirm it.
Step 3 — Write or reconcile DESIGN.md, then index it in AGENTS.md
- Choose the location (
SPEC.md §2): if the repo has a docs/ tree (DWP-native),
write docs/DESIGN.md alongside the other specs; if it has no docs/ tree,
write ./DESIGN.md at the root.
- If no
DESIGN.md exists → write it at the chosen location.
- If one already exists → reconcile additively (
SPEC.md §6): keep working
values, add missing canonical sections, and ask before any destructive change.
- Index it in
AGENTS.md (and therefore CLAUDE.md): add a reference to
DESIGN.md in the documentation index so agents discover it like the other
docs/ specs. This pointer — not the physical location — is what guarantees
discovery (SPEC.md §2).
Step 4 — Validate (the gate)
Run the validation step (SPEC.md §11):
DESIGN.md exists at the chosen location (docs/DESIGN.md or root) with all
canonical sections, and AGENTS.md references it.- Every documented value traces to the real design source (spot-check a few
against the stylesheet/config); inferred values flagged.
- Documented text-color pairings meet WCAG AA contrast; token references
resolve (no orphans/broken refs).
- File is Markdown-first and compact (~2–5K tokens); no build dependency added.
Step 5 — (Optional) install the /design-system delegator
If the developer wants a one-command refresh later, install a /design-system
delegator into the repo's .agents/commands/ (template:
templates/design-system-command.md) that re-runs this addon. Skip if not wanted —
a declined command leaves a baseline-conformant repo.
Failure-mode guardrails
- Never required, never blocking. If the developer declines, stop cleanly.
- Frontend only. Skip for backend/CLI/non-UI repos — applying it there is a defect.
- Reason about the tokens. Document the repo's real values; never paste a brand file.
- Reconcile, don't clobber. Preserve a working
DESIGN.md; ask before destructive edits.
- Protect accessibility. Capture the repo's contrast rules; don't document failing pairings.
- Reference, don't hard-bind. Follow the convention's shape, not its Alpha format details.
