custom-ui-spec
A highly customizable UI design specification system based on headless component libraries (shadcn/ui, Radix UI), integrating Apple HIG, Microsoft Fluent, Google Material Design, Anthropic Editorial Warm, OpenAI Swiss Modernist, and ArtCraft Studio Blueprint. Unlike using off-the-shelf frameworks (Ant Design, Element Plus), this skill is for scenarios requiring full control over component styles and DOM structure, emphasizing design freedom and brand customization. Use when: generating custom UI code, reviewing custom UI designs, or needing to follow platform-specific or AI-native design guidelines. Supports HIG / Fluent / Material / Anthropic / OpenAI / ArtCraft / All specification modes. Keywords: shadcn/ui, Radix UI, headless, custom components, HIG, Fluent, Material Design, Anthropic, Claude, OpenAI, ChatGPT, ArtCraft, editorial UI, modernist UI, blueprint UI.
Custom UI Spec
Overview
This skill provides strict definitions for six major design specifications — Apple HIG, Microsoft Fluent, Google Material Design, Anthropic Editorial, OpenAI Modernist, and ArtCraft Blueprint — to guide highly customizable UI implementations based on headless component libraries like shadcn/ui and Radix UI.
Unlike scenarios using off-the-shelf UI frameworks (e.g., TDesign), this skill is for projects that require full control over component anatomy and styling, emphasizing design freedom, brand customization, and cross-platform design consistency.
Specification Selection Decision Tree
Dimension A: Target Platform (default recommendation)
| Platform | Recommended Spec | Rationale |
|---|---|---|
| iOS / iPadOS / macOS / watchOS / tvOS | HIG | Native Apple ecosystem experience |
| Windows / Xbox | Fluent | Native Microsoft ecosystem experience |
| Android / Web / Flutter | Material | Native Google ecosystem experience |
| AI Research Hubs / Editorial / Long-form Docs | Anthropic Editorial | Warm literary authority, high readability, zero-shadow hairline structure |
| Conversational AI / Multimodal Galleries / Modern SaaS | OpenAI Modernist | Swiss geometric clarity, borderless pearl surfaces, prompt-first UX |
| Creative Studios / Local-First AI Workbenches / Pro Tools | ArtCraft Blueprint | Zero-radius CAD blueprint grid, corner crosshair ticks, 3-tier sunken viewports |
| Cross-platform / Unsure | Ask about design tone preference | See Dimension B |
Dimension B: Design Tone Preference (when platform is unclear)
| Design Tone | Recommended Spec | Typical Scenarios |
|---|---|---|
| Refined, native, restrained, layered | HIG | Utility apps, productivity software, Apple ecosystem products |
| Productive, professional, deep, luminous | Fluent | Enterprise software, office suites, Windows ecosystem products |
| Bold, graphical, tactile, dynamic | Material | Consumer apps, creative products, Google ecosystem products |
| Warm, literary, academic, hairline-structured | Anthropic Editorial | AI research portals, documentation hubs, academic journals, knowledge tools |
| Crisp, gallery-white, borderless, atmospheric | OpenAI Modernist | Conversational AI apps, generative media showcases (video/audio), modern workspaces |
| Architectural, zero-radius, blueprint-grid, industrial HUD | ArtCraft Blueprint | Creative AI studios, node workflow editors, 3D/video pipelines, developer tools |
Decision Flow:
User specified a spec explicitly?
├── Yes → Use the specified spec directly
└── No → User specified a target platform?
├── Yes → Recommend per Dimension A
└── No → Ask about design tone preference (Dimension B)
└── User chooses "All" → Comprehensive cross-check (flag cross-spec conflicts)
Usage Modes
Generation Mode
Before generating UI code:
- Determine the target spec using the decision tree
- Read the corresponding
references/<spec>.mdfor the complete specification - Implement compliant styles using headless components like shadcn/ui
- Run
scripts/validate_ui.pyfor automated validation - Self-check against
references/checklist.mditem by item - Output the validation report
Review Mode
When reviewing existing UI code/design:
- Determine the target spec based on code characteristics or user input
- Run
scripts/validate_ui.pyfor automated static analysis - Cross-check against
references/checklist.mditem by item - Output the validation report (Pass / Warning / Error)
Validation Flow
Three-step validation:
- Automated check: Run
scripts/validate_ui.py --spec <hig|fluent|material> --file <path>or--text <code> - Manual self-check: Agent cross-checks against
references/checklist.mditem by item - Report output: Combine automated results and manual review into a structured validation report
Color checks are skipped by default. Add --check-color to enable them.
Component Mapping Quick Reference
| Unified Name | HIG | Fluent | Material |
|---|---|---|---|
| Button | Button | Button | Button |
| TextField | Text Field | Input | Text Field |
| Checkbox | Checkbox | Checkbox | Checkbox |
| RadioButton | Radio Button | Radio | Radio Button |
| Switch | Toggle | Switch | Switch |
| Slider | Slider | Slider | Slider |
| ProgressIndicator | Progress View | Progress Bar | Progress Indicator |
| Menu | Menu | Menu | Menu |
| Dialog | Alert / Sheet | Dialog | Dialog |
| Card | — | Card | Card |
| List | List | List | List |
| NavigationBar | Navigation Bar | Navigation | App Bar / Bottom App Bar |
| TabBar | Tab Bar | Tab | Tabs |
| SegmentedControl | Segmented Control | — | — |
| Tooltip | Tooltip | Tooltip | Tooltip |
| Badge | Badge | Badge | Badge |
| Chip | — | Tag | Chip |
| DatePicker | Date Picker | Date Picker | Date Picker |
| Table | Table | Data Grid | Data Table |
| Breadcrumb | — | Breadcrumb | — |
| Select | Pop-up Button | Dropdown | Exposed Dropdown Menu |
| Autocomplete | — (inferred) | Combobox | — (inferred) |
| Textarea | Multiline Text Field | Textarea | Text Field (multiline) |
| NumberInput | Stepper + Field | SpinButton | — (inferred) |
| Upload | — (inferred) | — (inferred) | — (inferred) |
| Toast | — (inferred) | Toast | Snackbar |
| Notification | — (inferred) | — (inferred) | — (inferred) |
| Alert·Banner | — (inferred) | MessageBar | Banner |
| Skeleton | — (inferred) | Skeleton | — (inferred) |
| Drawer·Sidebar | Sidebar | NavigationView | Navigation Drawer |
| Pagination | — (inferred) | — (inferred) | — (inferred) |
| Stepper | — (inferred) | — (inferred) | Stepper |
| Sheet·ActionSheet | Action Sheet | — (inferred) | Bottom Sheet |
| Avatar | — (inferred) | Avatar / Persona | Avatar |
| Accordion | Disclosure | Accordion | — (inferred) |
| Carousel | Page Control | Carousel | Carousel |
| Timeline | — (inferred) | — (inferred) | — (inferred) |
| Tree | Outline View | TreeView | — (inferred) |
| Divider | Separator | Divider | Divider |
| Grid·Layout | — (inferred) | — (inferred) | Grid |
| Space·Stack | — (inferred) | Stack | — (inferred) |
| AspectRatio | — (inferred) | — (inferred) | — (inferred) |
| Popover | Popover | Popover | — (inferred) |
| Modal | Modal Sheet | Modal Dialog | Full-screen Dialog |
| FAB | — (inferred) | — (inferred) | FAB |
| SearchBar | Search Field | SearchBox | Search Bar |
| Rating | — (inferred) | Rating | — (inferred) |
| ColorPicker | Color Well | ColorPicker | — (inferred) |
| Calendar | Calendar View | Calendar | Date Calendar |
See references/component-specs.md for detailed definitions.
Resource Reference
| File | When to Read |
|---|---|
references/apple-hig.md | When HIG spec is selected |
references/microsoft-fluent.md | When Fluent spec is selected |
references/google-material.md | When Material spec is selected |
references/anthropic-editorial.md | When Anthropic Editorial spec is selected |
references/openai-modernist.md | When OpenAI Modernist spec is selected |
references/artcraft-blueprint.md | When ArtCraft Blueprint spec is selected |
references/component-specs.md | When detailed component definitions or cross-spec comparison is needed |
references/interaction-guidelines.md | When user interaction behavior specs (navigation/gestures/feedback/confirmation/undo) are needed |
references/checklist.md | When performing manual self-checks |
scripts/validate_ui.py | When running automated validation |
- Downloads
- 481All time
- Security audit
- Pass
- Last updated
- 4d ago
- Current version
- v0.2.0
- License
- MIT-0
