| name | do-wdr-ui-component |
| description | Implement CSS-only UI components for the do-web-doc-resolver design system. Use when creating new components, fixing component styles, or implementing GitHub issues tagged design-system/frontend in cli/ui/. Triggers include "create component", "implement badge/tooltip/modal", "add CSS for", "design system component", or any task involving cli/ui/components/. Covers token patterns, BEM naming, accessibility, dark mode, and the wave-based GitHub issue implementation workflow. |
| allowed-tools | Bash(git:*), Read, Write, Edit, Glob, Grep |
WDR UI Component Development
CSS-only components for the do-web-doc-resolver developer-first design system.
When to use
- Creating a new component CSS file in
cli/ui/components/
- Implementing a GitHub issue tagged
design-system or frontend
- Fixing component styles, accessibility, or dark mode issues
- Adding provider-specific badge variants
Component structure
Each component is a single flat .css file max 200 lines. Structure:
components/
├── badge.css
├── button.css
├── {component}.css ← new components go here
File template
:root {
--do-wdr-{component}-{property}: var(--do-wdr-{semantic-token});
--do-wdr-{component}-{variant}-{property}: var(--do-wdr-{semantic-token});
}
.do-wdr-{component} { }
.do-wdr-{component}--sm { }
.do-wdr-{component}--md { }
.do-wdr-{component}--lg { }
.do-wdr-{component}--success { }
.do-wdr-{component}__element { }
.do-wdr-{component}:focus-visible { outline: 2px solid var(--do-wdr-border-focus); outline-offset: 2px; }
@media (prefers-reduced-motion: reduce) {
.do-wdr-{component} { transition: none; animation: none; }
}
Token naming
--do-wdr-{component}-{element}-{variant}-{state}
--do-wdr-button-primary-bg-hover
--do-wdr-badge-provider-exa-bg
--do-wdr-kv-key-color
Required semantic tokens (from tokens/design_tokens.css)
- Surfaces:
--do-wdr-surface-bg, --do-wdr-surface-bg-elevated, --do-wdr-surface-bg-muted
- Text:
--do-wdr-text-primary, --do-wdr-text-secondary, --do-wdr-text-tertiary
- Borders:
--do-wdr-border-default, --do-wdr-border-subtle, --do-wdr-border-focus
- Signals:
--do-wdr-signal-success, --do-wdr-signal-warning, --do-wdr-signal-error, --do-wdr-signal-info
- Signal BGs:
--do-wdr-signal-success-bg, --do-wdr-signal-warning-bg, --do-wdr-signal-error-bg, --do-wdr-signal-info-bg
- Interactive:
--do-wdr-interactive-bg, --do-wdr-interactive-bg-hover, --do-wdr-interactive-bg-subtle
- Spacing:
--do-wdr-space-1 through --do-wdr-space-16
- Typography:
--do-wdr-font-sans, --do-wdr-font-mono, --do-wdr-text-xs through --do-wdr-text-3xl
- Motion:
--do-wdr-transition-colors, --do-wdr-duration-fast, --do-wdr-ease-out
- Data:
--do-wdr-data-row-alt, --do-wdr-data-row-hover, --do-wdr-data-row-selected
Accessibility requirements
Every component MUST have:
focus-visible outline (2px --do-wdr-border-focus, offset 2px)prefers-reduced-motion: reduce disabling all animations- Semantic HTML where applicable (
dl/dt/dd, role=progressbar, aria-describedby)
- No content conveyed by color alone
Implementation workflow
- Read the GitHub issue body for requirements and design reference
- Read
tokens/design_tokens.css for available semantic tokens
- Read 1-2 existing components (e.g.,
button.css, badge.css) for conventions
- Write the component CSS file using Write tool
- Update
components/README.md — replace issue link with file reference
- Commit:
git add cli/ui/components/{name}.css cli/ui/components/README.md && git commit -m "feat(ui): implement {Component} — issue #{N}"
If git commands fail, follow the retry sequence
before escalating: stash → abort rebase → abort merge → fetch main → retry.
Never retry more than 3 times.
References
Anti-patterns (never do these)
- Adding comments to CSS code
- Animating layout properties (width, height, margin) — transform/opacity only
- Using raw primitive tokens — always use semantic tokens
- Exceeding 200 lines per file
- Generic loading spinners without context
- Decorative animation or bouncing dots
