Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan/addons/design-system

deepworkplan-addon-design-system

Verified

Optional DeepWorkPlan addon that gives a repo with a user-facing interface surface a DESIGN.md (under docs/, indexed from AGENTS.md) — a Markdown design-system file any coding agent reads to generate interface output consistent with the repo's OWN conventions. Covers three profiles detected independently from real files — visual-ui (rendered web/mobile/desktop UI), cli-output (styled terminal output — semantic colors, panels, spinners, prompts, TTY/NO_COLOR degradation), and conversational (chat/email messaging — voice and register, message anatomy, per-platform rendering). Reasons about the repo's ACTUAL design source (CSS custom properties, Tailwind config, token files, component styles, a CLI display/theme module, or message-composition helpers) rather than copying a brand file; checks contrast (WCAG AA), color-is-not-the-only-carrier, plain-text fallbacks, and token integrity. A detected interface surface makes the evaluation and offer mandatory (with a clear recommendation), while installation always requires explicit acceptance — no profile is auto-applied, even in trust mode. Never offered for a repo with no interface surface (pure library, headless service, infra-only); 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 interface output — visual UI, terminal output, or outbound messages.

DeepWorkPlan — Design-System Addon

Give a repo with a user-facing interface surface a DESIGN.md — living under docs/ alongside the repo's other specs and indexed from AGENTS.md — so any human or AI agent generates interface output that matches the repo's own conventions, instead of the unstyled, statistically-common defaults an agent falls back to with no guidance. "Interface surface" is plural (SPEC.md §3): a rendered visual UI, styled CLI output, or a conversational surface (the product talks on chat/email) each count, as independent profiles that stack into the same single DESIGN.md. This is an opt-in addon — it is never required for a repo to be AI-first, and it is only for repos with at least one real interface surface.

The rule that overrides everything: REASON about the repo's source, 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; or its CLI display/theme module and print helpers; or its message-composition layer and documented voice rules (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) and never import another CLI's or bot's conventions wholesale: reference catalogs are inspiration for structure, never content.

Read these first (all relative inside the skill)

  • SPEC.md — the normative (RFC-2119) contract: interface-surface gate + the three profiles, canonical sections per profile, reason-don't-copy, reconcile-don't-clobber, accessibility & output integrity, pragmatic-reference posture, validation step.
  • templates/DESIGN.md.md — the annotated DESIGN.md skeleton (each canonical section per profile + 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, CLI rendering layers, conversational platforms) — where to find the design source 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. Detection makes the offer mandatory (SPEC.md §3.5): when any interface surface is detected — even an ambiguous one — onboarding evaluates it, records the detection rationale, and presents the addon with a clear recommendation; the evaluation and offer are not skippable in either mode. Every profile still requires explicit acceptance, including visual UI in trust mode; no profile is auto-applied. When no interface surface is detected the addon 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 add a newly relevant profile to it), or via the installed /design-system delegator if one was added.

Trust boundary (write scope)

allowed-tools includes write-capable Edit, Write, and Bash.

Writes: DESIGN.md (created once at the repo-root or docs/ location Step 3 reasons about, then reconciled on refresh; existing sections the developer wrote are preserved unless explicitly re-approved), the short AGENTS.md index/pointer entry Step 3 adds so humans and agents can find the file (merged — never over an existing section), and — optionally and only on acceptance — the /design-system delegator command under .agents/commands/. Everything the addon needs to "see" (existing components, styles, docs) is read-only analysis.

It MUST NOT: modify source components, styles, or any application file (DESIGN.md is a specification humans and agents read, not a code generator), invent tokens no real component uses, or apply a profile the developer declined.

The flow

Step 0 — Consent + interface-surface gate

  1. Confirm the developer wants a DESIGN.md (skip silently if declined — the repo stays baseline-conformant).
  2. Detect the repo's interface surfaces, profile by profile (SPEC.md §3):
    • visual-ui — stylesheets / CSS custom properties, a Tailwind config or @theme block, UI components (.tsx/.vue/.svelte/.astro), or a token/brand source.
    • cli-output — a CLI/TUI rendering library (rich, chalk, ink, lipgloss, ratatui, …) plus a deliberate rendering layer (a display.*/ui.* helper, semantic print helpers, documented output patterns). Skip the profile for a bare argument parser with raw unstyled prints.
    • conversational — a chat-platform SDK (Slack, Discord, Teams, …), a message-composition layer, or documented outbound-message voice rules.
  3. If no profile is detected, stop and tell the developer this addon does not apply. Otherwise, the offer is mandatory (§3.5): evaluate the detected signal, record the detection rationale, and offer each detected profile per its strength — strongly recommend visual-ui, recommend cli-output and conversational; an ambiguous signal still gets the offer, with the ambiguity named. Apply only profiles explicitly accepted by the developer. Existing acceptance need not be asked again; an explicit decline is respected for that run. Trust alone accepts none.

Step 1 — Locate the design source (the part you MUST reason about)

Find where each accepted profile'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.
  • CLI rendering layer → the display.*/output.*/ui.* helper module, its semantic styles and print helpers, spinner/panel/prompt wrappers, and any output best-practices doc.
  • Message composition layer → the helpers/templates that build outbound messages, their envelope kinds (DM/channel/thread/edit), and any documented voice/brand-naming rules (often in AGENTS.md or a skill doc).
  • 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 + a CLI display module). Read all that exist; the real files win over any preset assumption.

Step 2 — Reason out each canonical section, per accepted profile

Using templates/DESIGN.md.md, fill each accepted profile's sections from its design source (SPEC.md §4):

  • visual-ui — 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).
  • cli-output — Output voice & intent · Semantic colors & styles (success/ error/warning/info/highlight/dim mapped to the real theme) · Output components (panels, tables, spinners, progress, prompts — named after the real helpers) · Layout conventions · Degradation & environment (TTY vs pipe, NO_COLOR, stdout/stderr, exit codes) · Do's & don'ts.
  • conversational — Voice & register (tone, brevity, brand naming) · Message anatomy (envelope kinds + structure) · Platform rendering (only the platforms the repo actually targets) · Do's & don'ts.

One Overview and one Agent prompt guide serve the whole file (§4.1). 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. Never create sibling per-surface files (CLI_DESIGN.md, CONVERSATION_DESIGN.md) — one repo, one DESIGN.md.
  • If no DESIGN.md exists → write it at the chosen location. A single accepted profile keeps its sections at the top level; multiple accepted profiles get one top-level heading per profile (§4.1).
  • If one already exists → reconcile additively (SPEC.md §6): keep working values, add missing canonical sections — and when adding a new profile to an existing file, append its sections (grouping per §4.1) without rewriting the existing content. 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 for each accepted profile, and AGENTS.md references it; no sibling per-surface files were created.
  • Every documented value traces to the real design source (spot-check a few against the stylesheet/config/display module/message helpers); inferred values flagged.
  • Per-profile integrity (SPEC.md §7): text-color pairings meet WCAG AA (visual-ui); color is not the sole carrier of meaning and degradation rules are documented (cli-output); rich renderings note plain-text fallbacks (conversational); token references resolve (no orphans/broken refs).
  • New profiles were asked about before applying — never auto-applied.
  • File is Markdown-first and compact (~2–5K tokens single-profile, ≤ ~8K multi-profile); 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.
  • Interface surfaces only. Skip for repos with no interface surface of any kind (pure library, headless service, infra-only) — applying it there is a defect.
  • Offer mandatorily, accept explicitly. A detected interface surface makes the evaluation and offer mandatory in both modes; installation still needs explicit acceptance — no profile is auto-applied, even in trust mode. (The required local AI Diff Reviewer installs as baseline; the near-default dependency-upgrade delegator installs inert under the onboarding consent unless declined — neither applies a design profile.)
  • Reason about the source. Document the repo's real values; never paste a brand file or another product's conventions.
  • One file. Profiles stack inside DESIGN.md; never create per-surface siblings.
  • Reconcile, don't clobber. Preserve a working DESIGN.md; ask before destructive edits.
  • Protect integrity. Capture the repo's contrast rules (visual), degradation rules (CLI), and plain-text fallbacks (conversational); don't document failing patterns.
  • Reference, don't hard-bind. Follow the convention's shape, not its Alpha format details.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall