j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan/addons/design-system
deepworkplan-addon-design-system
VerifiedOptional 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.9 KB |
| SPEC.md | markdown | 21.7 KB |
| addon.json | config | 212 B |
| templates/DESIGN.md.md | markdown | 8.0 KB |
| templates/agent_prompt_guide.md | markdown | 2.2 KB |
| templates/design-system-command.md | markdown | 2.7 KB |
| templates/presets.md | markdown | 6.3 KB |
SPEC.md
View on GitHub# SPEC.md — Design-System Addon (Normative)
## Abstract
This document is the **normative specification** of the DeepWorkPlan
**design-system addon**: an opt-in capability that gives a repository with a
**user-facing interface surface** a **`DESIGN.md`** — placed under **`docs/`**
alongside the repo's other specs and indexed from `AGENTS.md` — a Markdown
design-system file that any coding agent reads to generate interface output
**consistent with the repo's own conventions**. It defines the
**interface-surface gate** (RFC-2119) and its three **profiles** (visual UI,
CLI output, conversational), the **location + `AGENTS.md` discovery** rule, the
**canonical sections** a `DESIGN.md` MUST carry per profile, the
**reason-don't-copy** rule, the **reconcile-don't-clobber** behavior, the
**pragmatic-reference** posture toward the upstream convention, the
**onboarding hook**, and the **validation** step.
The addon is **stack-aware**: it reasons about the repo's **actual** design
source (CSS custom properties, a Tailwind config, design-token files, component
styles — or a CLI rendering layer, or message-composition conventions) rather
than copying a third-party brand file. It is governed by `../README.md` and
`../../spec/ADDONS.md`: it is **never** required for baseline AI-first
conformance — a repo with zero optional addons is fully conformant.
## Status of This Document
| Field | Value |
|-------|-------|
| **Version** | 2.2.0 |
| **Status** | Stable |
| **Companions** | `SKILL.md`, `templates/DESIGN.md.md`, `templates/presets.md`, `templates/agent_prompt_guide.md`, `../README.md`, `../../spec/ADDONS.md` |
| **License** | MIT |
> **Divergence from 2.1.0.** Version 2.1.0 was **frontend/UI-scoped** and had a
> hard exclusion: a CLI or backend repo MUST have the addon skipped. Version
> 2.2.0 generalizes the gate to **interface surfaces** and introduces
> **profiles** (§3). The change is **additive and backwards compatible**: a
> `DESIGN.md` produced under 2.1.0 is a valid single-profile (`visual-ui`)
> `DESIGN.md` under 2.2.0, with **zero** migration required, and the visual
> profile's recommendation strength is unchanged.
## 1. Conventions
The RFC 2119 keywords (**MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**,
**MAY**, **OPTIONAL**) are interpreted as in
[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
Throughout, **`DESIGN.md`** is the design-system file this addon produces (at
`docs/DESIGN.md` by default, §2); an **interface surface** is any boundary
where the product meets a person (a rendered visual UI, styled terminal
output, or messages the product sends on a chat/email platform); a
**profile** is the per-surface flavor of the addon (§3); a **token** is a
named design value — for a visual surface a color, a type size, a spacing
step, a radius, an elevation; for a CLI surface a semantic style (success,
error, warning, dim) or an output component; for a conversational surface a
voice rule or a message-shape convention; and the **design source** is the
repo's real origin of those values (a stylesheet, a Tailwind config, a token
file, the component styles, a CLI display/theme module, or
message-composition helpers and their docs).
---
## 2. What the Addon Provides
- The addon **MUST** produce a single **`DESIGN.md`** — a Markdown file,
human-authorable and LLM-legible, that documents the repo's interface
conventions so an agent generating interface output follows them instead of
inventing statistically-common defaults. It **MUST** be version-controlled
and reviewable in pull requests.
- The addon **MUST NOT** produce sibling files per surface (no `CLI_DESIGN.md`,
no `CONVERSATION_DESIGN.md`): one repo, one `DESIGN.md`. Multiple accepted
profiles stack as sections inside the same file (§4.1) — `DESIGN.md` is the
canonical name agents discover.
- **Location (DWP-native default):** in a repo that follows the DWP documentation
standard — specs/docs centralized under `docs/` and indexed by `AGENTS.md` —
`DESIGN.md` **SHOULD** live at **`docs/DESIGN.md`**, alongside the other specs
(`ARCHITECTURE.md`, `STANDARDS.md`, `PRODUCT_SPEC.md`, …), **not** scattered at
the root. A repo with **no** `docs/` tree (or one mirroring the upstream
root convention) **MAY** instead place it at the repo root (`./DESIGN.md`).
- **Discovery is by reference, not by physical location.** Wherever it lives, the
addon **MUST** ensure `AGENTS.md` (and therefore `CLAUDE.md`) **references**
`DESIGN.md` in its documentation index, so any agent discovers it the same way it
discovers the rest of the `docs/` specs. The location matters less than the
`AGENTS.md` pointer being present.
- The file **SHOULD** stay compact: roughly 2–5K tokens for a single-profile
repo, and **SHOULD NOT** exceed roughly 8K tokens even when all three
profiles apply — it must fit comfortably in an agent's context window
alongside the task.
- The addon **MUST NOT** introduce a build dependency, a plugin, or an external
source of truth; `DESIGN.md` is plain Markdown readable by any agent.
---
## 3. Interface-Surface Gate (the part the addon reasons about)
- The addon is **interface-surface-scoped**. It **MUST** be offered (and
applied) only when the repo has at least one **user-facing interface
surface**, detected as one or more of the **profiles** below.
- The agent **MUST** detect each profile from **real files** — never from the
repo's name or archetype alone:
### 3.1 Profile: `visual-ui` — rendered visual interfaces
| Signal | Example evidence |
|--------|------------------|
| Stylesheet / tokens | `*.css`, `*.scss`, CSS custom properties, a `tokens.*` / `theme.*` file |
| Utility/theme config | `tailwind.config.*`, a Tailwind v4 `@theme` block in CSS, CSS-in-JS theme |
| UI components | `.jsx`/`.tsx`/`.vue`/`.svelte`/`.astro` components, a component library |
| Design assets | a brand/style guide doc, a design-tokens export, a Figma reference |
### 3.2 Profile: `cli-output` — styled terminal interfaces
| Signal | Example evidence |
|--------|------------------|
| CLI/TUI rendering library | `rich`, `textual`, `questionary` (Python); `chalk`, `ink`, `ora`, `prompts` (Node); `lipgloss`, `bubbletea` (Go); `colored`, `ratatui`, `indicatif` (Rust) |
| A deliberate rendering layer | a `display.*` / `output.*` / `ui.*` helper module that centralizes printing; semantic print helpers (`print_success`, `print_error`, …) |
| Output conventions doc | an output/display best-practices doc; documented spinner/panel/prompt patterns |
| Interactive prompts | a picker/menu/confirm layer (questionary, inquirer, survey) |
A bare argument parser whose output is unstyled raw prints is a **weak**
signal: the profile **SHOULD NOT** be offered when there is no deliberate
rendering layer to document.
### 3.3 Profile: `conversational` — the product talks on a messaging surface
| Signal | Example evidence |
|--------|------------------|
| Chat-platform SDK | `slack-sdk`/Bolt, `discord.js`/`discord.py`, `botbuilder` (Teams), Google Chat / Telegram / WhatsApp SDKs |
| Message composition layer | helpers or templates that build outbound messages (reports, notifications, replies); stable message-id / edit semantics |
| Voice conventions | documented tone/brevity/brand-naming rules for outbound messages (e.g. in `AGENTS.md` or a skill doc) |
| Other messaging surfaces | transactional email templates, SMS, voice/IVR prompt flows |
### 3.4 The gate
- A repo with **no** interface surface of any kind — a pure library with no
rendered output, a headless backend service, an infrastructure-only repo —
**MUST** have this addon **skipped**; applying it there is a defect.
- A repo **MAY** match several profiles (a web app with an ops CLI; a Slack bot
with an admin UI). Detection **MUST** evaluate each profile independently,
and each detected profile is offered independently (§3.5); the accepted
profiles compose into the single `DESIGN.md` (§4.1).
- The addon is **archetype-agnostic** (`ARCHETYPES.md`): it MAY be layered onto an
individual repo or onto a sub-repo of an orchestrator hub. No archetype is
excluded a priori — only the absence of any interface surface excludes a repo.
- **Backwards compatibility:** a `DESIGN.md` created before profiles existed is
a valid single-profile `visual-ui` file. Re-running the addon on such a repo
**MUST NOT** require restructuring it; new profiles are only **added** when
detected and accepted (§6).
### 3.5 Recommendation Strength — per profile
This addon is **never** part of the baseline (a repo with no optional addons
is fully conformant — `ADDONS.md` §2). When a profile's signal **is** detected,
its recommendation strength differs:
- **Detection makes the offer mandatory; it never makes the install
automatic.** When any interface-surface signal is detected — even an
ambiguous one — the `onboard` flow **MUST** evaluate it, present the addon,
and record the detection rationale with the offer; skipping the evaluation
or the offer (for example because the run is in trust mode) is a defect.
The offer carries a clear recommendation: **`visual-ui` — strongly
recommend when detected**; **`cli-output` and `conversational` — recommend
when detected**; an ambiguous signal still gets the offer, with the
ambiguity named.
- **Installation is acceptance-gated in both guided and trust modes.** Every
profile **MUST** have explicit developer acceptance before application; no
profile is auto-applied. A prior request naming the addon or profiles
counts, and the flow **MUST NOT** ask again for an already accepted action;
an explicit decline is respected for that run. Trust mode alone does not
accept any optional addon.
- When a profile's signal is **not** detected, the flow **MUST NOT** offer that
profile; when **no** profile is detected, the flow **MUST NOT** offer the
addon at all (§3.4).
- Declining — any profile, or all of them — **MUST** always remain possible,
and a declined addon **MUST** leave a fully baseline-conformant repo.
Detection changes the recommendation, never the authorization.
This keeps `design-system` in the **strongest conditional tier** among the
addons for visual repos — because a repo that *has* a design system almost
always benefits from capturing it as `DESIGN.md` — while the newer profiles
earn their way in explicitly.
---
## 4. Canonical Sections of `DESIGN.md`
### 4.1 Profile composition (one file, stacked sections)
- A **single-profile** `DESIGN.md` carries that profile's canonical sections at
the top level — exactly the 2.1.0 shape for `visual-ui`.
- A **multi-profile** `DESIGN.md` **MUST** group each accepted profile's
sections under one top-level heading per profile (e.g. `## Visual UI`,
`## CLI output`, `## Conversational`), in any order that fits the repo.
- The file **MUST** carry exactly **one** Overview and exactly **one** Agent
Prompt Guide for the whole file, regardless of profile count; Do's & Don'ts
**MAY** be per profile or combined, as long as every profile's guardrails are
present.
- Section titles MAY be adapted to the repo's voice; the substance MUST be
present. Each section is **filled by reasoning about the design source**,
never copied from a brand file or another product's conventions.
### 4.2 `visual-ui` canonical sections
1. **Overview / Atmosphere** — brand personality, emotional tone, the design's
intent in one short paragraph.
2. **Color Palette & Roles** — semantic colors (primary, secondary, neutral,
surface, accent, state colors) with values **and** their functional role; light
and dark variants where the repo supports dark mode.
3. **Typography** — font families, the type scale (sizes/weights/line-heights), and
when each level is used.
4. **Layout & Spacing** — the spacing scale (base unit + steps), grid/container
strategy, and whitespace principles.
5. **Elevation & Depth** — shadow/surface hierarchy and how depth is expressed.
6. **Shapes** — border-radius scale and corner language; border/hairline treatment.
7. **Components** — the repo's key UI patterns (buttons, inputs, cards, nav, …)
described in terms of the tokens above, including interaction states.
8. **Responsive Behavior** — breakpoints and touch-target expectations.
9. **Do's and Don'ts** — explicit guardrails for agent behavior, including
**accessibility constraints** the repo enforces (see §7).
10. **Agent Prompt Guide** — a short "how to use this file" block telling a
downstream agent to follow `DESIGN.md` and how to reference tokens.
### 4.3 `cli-output` canonical sections
1. **Output Voice & Intent** — how the tool talks in the terminal: terse or
verbose, emoji policy, capitalization, error-message register.
2. **Semantic Colors & Styles** — the success/error/warning/info/highlight/dim
roles mapped to the repo's **real** theme (the rich/chalk/lipgloss styles
actually defined), never raw color names chosen ad hoc.
3. **Output Components** — the repo's rendering patterns: panels vs plain
lines, tables, status spinners, progress bars, interactive prompts and
pickers — named after the real helpers (`print_success`, `print_panel`, …).
4. **Layout Conventions** — blank-line policy, indentation, width handling,
when to use a panel vs a one-liner.
5. **Degradation & Environment** — TTY vs piped output, `NO_COLOR`/forced
color, narrow terminals, stdout-vs-stderr discipline, exit-code
conventions, quiet/JSON output modes where they exist.
6. **Do's and Don'ts** — guardrails such as "all output goes through the
display helper, never raw `print()` outside it" and the integrity rules
of §7.
7. **Agent Prompt Guide** — shared with the file (§4.1).
### 4.4 `conversational` canonical sections
1. **Voice & Register** — tone, person, brevity targets, language policy, and
**brand-naming rules** (exact product spellings) for outbound messages.
2. **Message Anatomy** — the envelope kinds the product sends (DM, channel
post, thread reply, edit-in-place) and the structure of each: length
targets, what a report leads with, what is never included.
3. **Platform Rendering** — how the same message renders per platform the repo
**actually targets** (e.g. Slack `mrkdwn`, Discord markdown, Teams adaptive
cards, Google Chat, email HTML/plain text). One section; per-platform rows.
4. **Do's and Don'ts** — guardrails such as audience rules (describe outcomes,
never internals like plan IDs or file paths), brand-name spelling, and the
plain-text-fallback rule of §7.
5. **Agent Prompt Guide** — shared with the file (§4.1).
- Values **SHOULD** be expressed as **named tokens** with human-readable usage
notes; the file **MAY** additionally carry a machine-readable token block
(e.g. front matter) when the repo already maintains structured tokens, but a
Markdown-first table is sufficient and preferred for authorability.
---
## 5. Reason, Don't Copy
- Every value in `DESIGN.md` **MUST** be **derived from the repo's real design
source** — the stylesheet, Tailwind config, token files, or component styles;
the CLI display/theme module and its helpers; the message-composition layer
and its documented voice rules — whatever actually exists.
- The addon **MUST NOT** paste a third-party brand's `DESIGN.md` (e.g. a catalog
entry for Stripe, Linear, or any other product) into the target repo, and
**MUST NOT** import another CLI's or bot's conventions wholesale. Reference
catalogs are **inspiration for structure**, never the content.
- When a value is genuinely undefined in the repo, the addon **SHOULD** infer the
most consistent value from existing usage and **MUST** flag it as inferred (so a
human can confirm), rather than fabricate an unrelated value.
---
## 6. Reconcile, Don't Clobber
- If a `DESIGN.md` (or an equivalent design-token source) **already exists**, the
addon **MUST** reconcile additively — preserving values that already work and
bringing the rest toward the canonical-section shape.
- Adding a newly accepted profile to an existing `DESIGN.md` **MUST** be
additive: append the new profile's sections (grouping per §4.1 when the file
becomes multi-profile) without rewriting the existing profile's content.
- The addon **MUST NOT** overwrite or delete an existing `DESIGN.md` or token file
wholesale. Per `AGENT_PROTOCOL.md`, any destructive change to an existing file
**MUST** be approved by the developer first.
- The addon **MUST** record what it changed (added sections/profiles, reconciled
values, inferred values flagged for confirmation).
---
## 7. Accessibility & Output Integrity
- The Do's and Don'ts **MUST** capture the repo's **real accessibility and
integrity rules** when the repo documents them, so agents do not regress them.
- **`visual-ui`:** documented color pairings intended for text **SHOULD** meet
**WCAG AA** contrast (4.5:1 normal, 3:1 large) and the addon **SHOULD**
sanity-check the pairings it documents.
- **`cli-output`:** color **MUST NOT** be documented as the sole carrier of
meaning (output must stay legible when piped or with `NO_COLOR`); where the
repo honors `NO_COLOR`/TTY detection, the degradation rules **MUST** be
documented (§4.3.5).
- **`conversational`:** every documented rich rendering (blocks, cards, HTML)
**SHOULD** have a plain-text fallback noted for platforms or clients that
strip formatting.
- Token references inside `DESIGN.md` **MUST** resolve — no orphaned or broken
references: a component referencing an undefined token, a documented CLI
helper that does not exist in the code, or a documented platform the repo
does not actually target.
---
## 8. Pragmatic Reference, Not Hard Binding
- The addon **references** the emerging `DESIGN.md` convention (introduced by
Google Stitch; popularized by community catalogs) as the **shape** to follow, but
**MUST NOT** hard-bind to that convention's evolving/Alpha format details. The
`cli-output` and `conversational` profiles extend that shape to non-visual
surfaces while keeping the same file and discovery convention.
- DWP's `DESIGN.md` is **Markdown-first**; adopting any specific machine-readable
token schema (e.g. W3C Design Tokens front matter) is **OPTIONAL** and applied
only when it fits the repo.
---
## 9. Onboarding Hook + Optional `/design-system` Delegator
- The addon's onboarding hook (`SKILL.md`) is offered by `onboard` Phase 7b as an
**opt-in** step, **only for repos with a detected interface surface** (§3),
profile by profile (§3.5), and **MUST NOT** be applied without acceptance. A
declined addon leaves a baseline-conformant repo.
- The addon **MAY** install a `/design-system` delegator command into the target
repo's `.agents/commands/` (to regenerate/refresh `DESIGN.md` later; template:
`templates/design-system-command.md`). Installing the command is **OPTIONAL**; a
declined addon installs **no** command.
---
## 10. Relationship to Per-Feature Design Docs (positioning)
- This addon provides a **repo-level, persistent design-system file**. It is
**distinct** from a **per-feature technical design document** (the
"requirements → design → tasks" `design.md` of tool-bound spec-driven workflows).
- DeepWorkPlan deliberately does **not** ship a separate per-feature design-doc
archetype: a DWP plan's README (Goal + Context), each task's Context and
**Acceptance Criteria**, and the **validation gates** already fulfill the
per-feature design role. This addon fills the one gap that role does not cover —
durable, repo-native **interface** design context.
---
## 11. Validation Step (run after applying)
The addon is correctly applied when **all** hold:
1. The repo was confirmed to have at least one **interface surface** (§3), each
applied profile's signal was **detected from real files**, and the addon was
**skipped** for repos with no interface surface of any kind.
2. A `DESIGN.md` exists with all canonical sections **for each accepted
profile** (§4) — at **`docs/DESIGN.md`** for a repo with a `docs/` tree
(DWP-native default), or at the repo root for a repo without one (§2); no
sibling per-surface files were created.
3. **`AGENTS.md` references `DESIGN.md`** in its documentation index (so agents
discover it like the other `docs/` specs) (§2).
4. Every documented value is **traceable to the repo's real design source** (§5);
no third-party brand file was pasted; inferred values are flagged.
5. An **existing** `DESIGN.md`/token source, if present, was **reconciled** (§6),
not clobbered — including when a new profile was added to it; destructive
changes were approved.
6. Per-profile integrity holds (§7): documented 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) in every profile.
7. The file is Markdown-first and compact (§2); no build dependency was
introduced.
8. New profiles (`cli-output`, `conversational`) were **asked about** before
applying — never auto-applied, even in trust mode (§3.5).
9. If a `/design-system` delegator was offered and accepted, it exists in the
repo's `.agents/commands/`; if declined, none was installed (§9).
---
## 12. References
- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
- `SKILL.md` (the onboarding hook + flow), `templates/*` (reasoning aids)
- `../README.md` (addon mechanism), `../../spec/ADDONS.md` (concept + pointer)
- `AGENT_PROTOCOL.md` (approval gates), `ARCHETYPES.md` (archetypes)
- [W3C Design Tokens](https://www.w3.org/community/design-tokens/) (optional token schema)
- [NO_COLOR](https://no-color.org/) (CLI color-suppression convention)
---
*Part of the DeepWorkPlan methodology v5.0.0, MIT License, by [Dailybot](https://dailybot.com) / dailybotops.*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |