| name | designing-workbench-design-system |
| description | Use when defining ShotgunCV frontend UI foundations, design tokens, component states, accessibility rules, layout density, or implementation handoff constraints. |
Designing Workbench Design System
Overview
ShotgunCV's design system preserves repeatable decisions for a local, Chinese-first, artifact-driven workbench: tokens, components, states, accessibility, content tone, and density. It should constrain the UI enough that new screens feel like the same operational product.
Foundations
| Foundation | Rule |
|---|
| Color | Use cold neutrals for structure, semantic colors for status/risk, and restrained accents for focus. |
| Typography | Use compact hierarchy; avoid viewport-scaled font sizes and oversized headings inside workbench panels. |
| Spacing | Use predictable steps; keep dense pages readable through grouping, not whitespace excess. |
| Radius | Default to small radii for operational UI. |
| Elevation | Use borders and subtle shadows for layers, not decorative depth. |
| Motion | Use motion to preserve orientation, never to delay repeated work. |
| Language | Default visible copy to Chinese; keep English only for technical identifiers and artifact names. |
Component State Contract
Every reusable component should define:
- Default, hover, focus-visible, active, disabled.
- Loading, empty, error, partial, legacy, and success where applicable.
- Keyboard behavior and accessible name.
- Text overflow and wrapping strategy for Chinese plus English identifiers.
- Mobile behavior.
- Data freshness, artifact provenance, or masked metadata when showing generated or evaluated content.
ShotgunCV Fit
- Tokens should support pipeline status, gate status, risk severity, evidence strength, artifact mode, and review state.
- Components should work for Chinese primary text with English identifiers.
- Generated content blocks should include source/evidence slots by default.
- Run artifact views should share status, empty, partial, legacy, and error components.
- Settings controls must protect API keys, raw CV/JD text, and unnecessary full local paths.
Handoff Rules
- Document tokens before creating one-off styles.
- Prefer existing design-system primitives over bespoke CSS for common controls.
- Keep icon buttons accessible with labels or tooltips.
- Verify color contrast and keyboard paths for every task-critical control.
- Avoid building separate visual languages for AI panels and normal workbench panels.
- Remove dead SaaS placeholders, decorative gradients, repeated shadows, and duplicated chip systems.
Common Mistakes
- Treating the design system as a component gallery only.
- Letting every feature define its own status colors.
- Using gradients or decorative effects as product identity.
- Designing only the happy path.
- Ignoring Chinese text expansion and mixed-language labels.
- Reusing generic SaaS language that implies accounts, teams, remote queues, CRM, or auto-delivery.
Checklist
References
