tomevault-io Frontend Governance Skill
Design Philosophy: Contemplative
UI must exhibit restraint, intentionality, and quiet confidence. Reject the generic SaaS aesthetic. Every element earns its place through purpose, not decoration.
Semantic Token System
All styling MUST use the project's semantic tokens. Direct color values are forbidden.
Background Layers
| Token | Usage | Tailwind Class |
|---|---|---|
--color-void |
Page background, deepest | bg-void |
--color-surface |
Card backgrounds, containers | bg-surface |
--color-elevated |
Modals, popovers, dropdowns | bg-elevated |
Text Hierarchy
| Token | Usage | Tailwind Class |
|---|---|---|
--color-text-primary |
Headings, body text | text-text-primary |
--color-text-secondary |
Muted text, labels | text-text-secondary |
--color-text-tertiary |
Disabled, hints, captions | text-text-tertiary |
Accent Colors
| Token | Usage | Tailwind Class |
|---|---|---|
--color-accent-warm |
Warm highlights, warnings | text-accent-warm |
--color-accent-cool |
Links, interactive states | text-accent-cool |
--color-accent-dream |
Purple accent, special | text-accent-dream |
Typography
| Token | Usage | Tailwind Class |
|---|---|---|
--font-heading |
Display text, headings | font-heading |
--font-data |
Numbers, code, tabular | font-data |
Forbidden Patterns (Anti-Slop)
The following patterns are explicitly banned. Their presence indicates "AI slop" and must be rejected:
Visual Anti-Patterns
- Gradient Crutch:
bg-gradient-to-*used decoratively without semantic purpose - Rounded-XL Addiction: Excessive
rounded-xl,rounded-2xl,rounded-3xlon every element - Skeleton Aesthetic: Gray placeholder boxes as permanent design elements
- Shadow Spam: Multiple layered shadows (
shadow-lg shadow-xl) for "depth" - Border Radius Inconsistency: Mixing radius values without system
Color Anti-Patterns
- Hardcoded Colors:
bg-gray-900,text-white,#1a1a1a,rgb(...),hsl(...) - Tailwind Palette Direct:
bg-blue-500,text-slate-400(use semantic tokens) - Opacity Hacks:
bg-black/50instead of proper elevation tokens
Layout Anti-Patterns
- Flexbox Soup: Nested flex containers without clear hierarchy
- Magic Numbers:
mt-[47px],w-[312px](use spacing scale) - Container Nesting: Excessive wrapper divs for spacing
Typography Anti-Patterns
- Font Size Chaos: Arbitrary text sizes without hierarchy
- Weight Overload: Bold everything for emphasis
- Line Height Neglect: Default line heights on dense text
Component Guidelines
Prefer Radix/shadcn Primitives
When available, use Radix UI primitives or shadcn/ui components. These provide:
- Accessibility out of the box
- Keyboard navigation
- Focus management
- ARIA compliance
Server Components by Default
All components are React Server Components unless they require:
- Event handlers (
onClick,onChange) - React hooks (
useState,useEffect) - Browser APIs (
window,document)
Client components must import client-only at the top.
Design Intent Protocol
Before generating any UI component, emit a <design_intent> block in the conversation:
<design_intent>
Component: [Name]
Purpose: [Single sentence]
Tokens: [List semantic tokens to be used]
Hierarchy: [Visual hierarchy description]
Interactions: [If any]
</design_intent>
CRITICAL: The <design_intent> block is ephemeral. It appears in conversation only and is NEVER committed to the codebase. It is a meta-cognitive tool for ensuring intentional design, not a code artifact.
Validation Checklist
Before presenting any UI code:
- All colors use semantic tokens (no hardcoded values)
- Typography uses
--font-headingor--font-datawhere appropriate - No forbidden patterns present
- Component has clear visual hierarchy
- Spacing uses Tailwind scale (no magic numbers)
- Server/Client boundary is correct
Converted and distributed by TomeVault — claim your Tome and manage your conversions.