```
### Rules
- All spacing values must be multiples of 4px
- Use Tailwind spacing utilities, never arbitrary `px` values
- Nest spacing: outer containers use larger values, inner elements use smaller
- Consistent gap hierarchy: section (48px) > panel (24-32px) > content (16px) > elements (8px) > micro (4px)
Key decisions:
- Base unit: 8px (with 4px half-step for micro adjustments)
- Never use odd pixel values or non-grid-aligned spacing
- Prefer `gap` and `space-y`/`space-x` over individual margins
- Scale spacing with viewport using responsive utilities (`gap-4 md:gap-6 lg:gap-8`)
### Define all interactive component states with consistent visual feedback patterns — HIGH
## Interactive Component States
**Incorrect -- button with only default state:**
```tsx
// WRONG: No hover, focus, disabled, or loading states
function Button({ children, onClick }) {
return (
);
}
// User gets no feedback on hover, no focus ring for keyboard users,
// no visual change when disabled, no loading indicator
```
**Correct -- button with all 6 states plus animation:**
### Required States for Interactive Components
| State | Visual Indicator | Purpose |
|-------|-----------------|---------|
| Default | Base styling | Resting appearance |
| Hover | Subtle background shift, cursor change | Indicates interactivity |
| Focus | Visible ring (2px offset) | Keyboard navigation feedback |
| Active/Pressed | Scale down or darken | Confirms click/tap registered |
| Disabled | Reduced opacity, no pointer events | Shows unavailability |
| Loading | Spinner + disabled interaction | Async operation in progress |
### TypeScript Interface
```typescript
interface ComponentStateProps {
isDisabled?: boolean;
isLoading?: boolean;
// Default, hover, focus, active are handled via CSS
}
```
### Tailwind State Classes
```tsx
function Button({ children, onClick, isDisabled, isLoading }: ComponentStateProps & {
children: React.ReactNode;
onClick?: () => void;
}) {
return (
);
}
```
### Motion Presets
| Context | Animation Name | CSS/Tailwind | Duration | Easing |
|---------|---------------|--------------|----------|--------|
| Page transitions | `pageFade` | `animate-in fade-in` | 200ms | ease-out |
| Modals | `modalContent` | `animate-in zoom-in-95 fade-in` | 200ms | ease-out |
| List items | `staggerItem` | `animate-in slide-in-from-bottom-2` | 150ms | ease-out |
| Card hover | `cardHover` | `hover:-translate-y-1 hover:shadow-lg` | 200ms | ease-in-out |
| Button tap | `tapScale` | `active:scale-[0.98]` | 100ms | ease-in |
| Toast enter | `toastSlideIn` | `animate-in slide-in-from-right` | 300ms | ease-out |
```tsx
// Staggered list animation
{items.map((item, i) => (
{item.content}
))}
```
### Accessibility Contrast Requirements
| Element | Minimum Ratio | Target Ratio | WCAG Level |
|---------|--------------|--------------|------------|
| Body text | 4.5:1 | 7:1 | AA / AAA |
| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 | AA / AAA |
| UI components (borders, icons) | 3:1 | 4.5:1 | AA |
| Focus indicators | 3:1 | 4.5:1 | AA |
### State Checklist for New Components
Every interactive component must define:
1. **Default** -- base visual appearance
2. **Hover** -- `hover:` modifier with subtle visual shift
3. **Focus** -- `focus-visible:ring-2` (never remove focus outlines)
4. **Active** -- `active:` feedback (scale, darken, or both)
5. **Disabled** -- `disabled:opacity-50 disabled:pointer-events-none`
6. **Loading** -- spinner icon, disabled interaction, aria-busy="true"
Key decisions:
- Always use `focus-visible` (not `focus`) to avoid showing rings on mouse click
- Keep transitions under 200ms for interactive feedback (longer feels sluggish)
- Use `prefers-reduced-motion` media query to disable animations for accessibility
- Test all states in Storybook with a dedicated "States" story per component
### Define consistent design tokens to enable global theme changes without visual drift — HIGH
## Design System Token Architecture
**Incorrect — hardcoded values and CSS variable abuse:**
```tsx
// WRONG: Hardcoded colors
// WRONG: CSS variables in className (use semantic tokens instead)
```
### Rules
- Never use arbitrary font sizes -- always use the scale tokens
- Pair weights intentionally: body=normal, labels=medium, headings=semibold
- Use `leading-tight` for headings, `leading-normal` for body, `leading-relaxed` for long-form
- Maximum 2 font families per project (1 sans-serif + 1 monospace is ideal)
- Responsive scaling: `text-2xl md:text-3xl lg:text-4xl` for page titles
Key decisions:
- Base size: 16px (`text-base`) -- browser default, accessible
- Scale ratio: ~1.25 (Major Third) for harmonious progression
- Weight hierarchy: normal < medium < semibold < bold (never skip 2+ levels)
- Line height decreases as font size increases
### Design intentional empty states with clear structure, actionable CTAs, and skeleton-first loading — HIGH
## Empty State Patterns
**Incorrect — blank screen and unusable no-results state:**
```tsx
// WRONG: Renders nothing when list is empty
function ProjectList({ projects }) {
return (
{projects.map(p =>
{p.name}
)}
)
}
// WRONG: Clinical message with no guidance or action
{projects.length === 0 &&
No projects.
}
// WRONG: Flash empty state before data loads (jarring UX)
{!isLoading && data.length === 0 && }
{isLoading && }
```
**Correct — skeleton-first, then structured empty state:**
```tsx
// RIGHT: Skeleton while loading → empty state only if data is truly absent
function ProjectList({ isLoading, projects }: Props) {
if (isLoading) return
if (projects.length === 0) return
return (
{projects.map(p =>
{p.name}
)}
)
}
// RIGHT: Structured empty state — icon + headline + description + CTA
function EmptyProjects() {
return (
{/* 1. Illustration or icon */}
{/* 2. Encouraging headline (not clinical) */}
Create your first project
{/* 3. Context description */}
Projects help you organise work and collaborate with your team.
Get started in under a minute.
{/* 4. Primary action */}
)
}
```
### Empty State Taxonomy
| Cause | Tone | CTA Example |
|-------|------|-------------|
| First-time (onboarding) | Encouraging, welcoming | "Create your first project" |
| No search results | Neutral, helpful | "Try different keywords or clear filters" |
| Error / failed to load | Reassuring, recovery | "Something went wrong — try again" |
| Permission / access | Clear, non-alarming | "Ask your admin for access" |
### Structure Checklist
```
[x] Icon or illustration (visual anchor)
[x] Headline — actionable, not clinical ("Create X" not "No X found")
[x] Description — 1-2 sentences of context
[x] Primary CTA button — one clear next step
[ ] Optional: secondary link for help docs
```
### Key Decisions
| Decision | Recommendation |
|----------|----------------|
| Blank screen | Never acceptable — always design an empty state |
| Loading order | Skeleton first → empty state if truly empty (no flash) |
| Headline tone | Encouraging and action-oriented, never clinical |
| CTA count | One primary action maximum per empty state |
| Role attribute | `role="status"` on the container for screen reader announcement |
| Cause-specific | Different empty states for first-time, no-results, error, permissions |
### Build performant forms with React Hook Form v7 controlled renders and validation — HIGH
## React Hook Form Patterns
Production form patterns with React Hook Form v7 for controlled rendering, field arrays, wizards, and file uploads.
**Incorrect — uncontrolled form with useEffect fetch:**
```tsx
// WRONG: Fetching in useEffect, manual state management
function BadForm() {
const [email, setEmail] = useState('');
const [errors, setErrors] = useState({});
useEffect(() => {
// Manual validation on every render...
if (!email.includes('@')) setErrors({ email: 'Invalid' });
}, [email]);
return setEmail(e.target.value)} />;
}
```
**Correct — React Hook Form with Zod resolver:**
```tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
const userSchema = z.object({
email: z.email('Please enter a valid email'),
password: z.string().min(8, 'Minimum 8 characters'),
confirmPassword: z.string(),
}).refine((data) => data.password === data.confirmPassword, {
message: "Passwords don't match",
path: ['confirmPassword'],
});
type UserForm = z.infer;
function SignupForm() {
const {
register,
handleSubmit,
formState: { errors, isSubmitting },
} = useForm({
resolver: zodResolver(userSchema),
defaultValues: { email: '', password: '', confirmPassword: '' },
mode: 'onBlur', // Validate on blur, not every keystroke
});
return (
);
}
```
**Field arrays for dynamic fields:**
```tsx
import { useFieldArray } from 'react-hook-form';
function OrderForm() {
const { control, register } = useForm({
defaultValues: { items: [{ productId: '', quantity: 1 }] },
});
const { fields, append, remove } = useFieldArray({ control, name: 'items' });
return (
<>
{fields.map((field, index) => (
{/* Use field.id, NOT index */}
))}
);
}
```
**Controller for third-party components:**
```tsx
import { Controller } from 'react-hook-form';
(
)}
/>
```
**Key rules:**
- Always provide `defaultValues` (prevents uncontrolled-to-controlled warnings)
- Use `mode: 'onBlur'` for better performance (not every keystroke)
- Use `field.id` as key in field arrays, never index
- Use `Controller` for non-native inputs (date pickers, selects, rich text)
- Add `noValidate` to form element when using Zod (disable browser validation)
- Use `aria-invalid` and `role="alert"` for accessibility
### Validate forms with Zod type-safe schemas on both client and server sides — HIGH
## Zod Validation & Server Actions
Type-safe validation with Zod schemas shared between client forms and React 19 Server Actions.
**Incorrect — client-only validation without server check:**
```tsx
// WRONG: Client validation only — bypassable with DevTools
function ContactForm() {
const handleSubmit = (e: FormEvent) => {
if (!email.includes('@')) return; // Client-only, easily bypassed!
fetch('/api/contact', { body: JSON.stringify({ email }) });
};
}
```
**Correct — shared Zod schema for client AND server:**
```typescript
// schemas/contact.ts — Shared validation (client + server)
import { z } from 'zod';
export const contactSchema = z.object({
name: z.string().min(2, 'Name must be at least 2 characters'),
email: z.email('Please enter a valid email'),
message: z.string().min(10, 'Message must be at least 10 characters'),
});
export type ContactForm = z.infer;
```
**Server Action with Zod validation (React 19):**
```typescript
// actions.ts
'use server';
import { contactSchema } from '@/schemas/contact';
export async function submitContact(formData: FormData) {
const result = contactSchema.safeParse({
name: formData.get('name'),
email: formData.get('email'),
message: formData.get('message'),
});
if (!result.success) {
// z.treeifyError() replaces deprecated .flatten() (Zod 4).
// Shape differs: per-field messages live at tree.properties[field].errors
const tree = z.treeifyError(result.error);
return { errors: tree.properties };
}
await saveContact(result.data);
return { success: true };
}
// Component with useActionState
'use client';
import { useActionState } from 'react';
import { submitContact } from './actions';
function ContactForm() {
const [state, formAction, isPending] = useActionState(submitContact, null);
return (
);
}
```
**Advanced Zod patterns:**
```typescript
// Async validation (username availability)
const usernameSchema = z.object({
username: z.string()
.min(3, 'At least 3 characters')
.refine(async (value) => {
const available = await checkUsernameAvailability(value);
return available;
}, 'Username already taken'),
});
// Use mode: 'onBlur' to avoid async validation on every keystroke
useForm({ resolver: zodResolver(usernameSchema), mode: 'onBlur' });
// Transform + validate
const priceSchema = z.object({
price: z.string()
.transform((val) => parseFloat(val))
.pipe(z.number().positive('Must be positive')),
});
// Discriminated union for conditional fields
const paymentSchema = z.discriminatedUnion('method', [
z.object({ method: z.literal('card'), cardNumber: z.string().length(16) }),
z.object({ method: z.literal('paypal'), paypalEmail: z.email() }),
]);
```
**Key rules:**
- Share Zod schemas between client and server — single source of truth
- Always validate on server even if client validation passes (never trust client)
- Use `safeParse` (not `parse`) for server actions to return errors instead of throwing
- Use `z.infer<typeof schema>` for automatic TypeScript types
- Async validation: combine with `mode: 'onBlur'` to avoid excessive API calls
- Custom error messages in every `.email()`, `.min()`, `.refine()` call
### shadcn/ui v4 Style System — 6 Styles + Preset Codes — HIGH
## shadcn/ui v4 Style System
shadcn CLI v4 ships 6 visual styles that rewrite component class names — not just CSS variables. Each style defines its own radius, elevation, spacing, and visual weight. Detect the project's style from `components.json` and apply the correct classes.
**Incorrect — hardcoding classes without checking project style:**
```tsx
// Assumes rounded-md everywhere — wrong for Luma (rounded-4xl) or Lyra (rounded-none)
const Card = ({ children }: CardProps) => (
```
## Key Rules
- Use `@theme` in CSS for all configuration — no `tailwind.config.js`
- Container queries are native — do not install `@tailwindcss/container-queries`
- Use `@sm:`, `@md:`, `@lg:` variants for container-width breakpoints
- Use `@max-*:` variants for max-width container queries
- Name containers with `@container/<name>` for targeted queries
- Use `/name` suffix on variants to target specific named containers
- Migrate existing `tailwind.config.js` to `@theme` block when upgrading to v4
Reference: [Tailwind CSS v4 Docs](https://tailwindcss.com/docs)
### Apply numeric typography thresholds for line length, line height, and font scale — HIGH
## Typography Thresholds
**Incorrect — unconstrained text and cascading em bugs:**
```tsx
// WRONG: Unbounded paragraph width causes too-long lines (eye fatigue)
Long body copy...
// WRONG: em units for font-size cause cascading multiplication
{/* Actually 1.44× root — bug! */}
Nested text
// WRONG: Line height too tight for body text
Body copy with 1.25 line height
// WRONG: Font weight 500 for "emphasis" — too subtle
Important
// WRONG: Inline links without underline (accessibility failure)
Click here
```
**Correct — constrained width, rem scale, proper line height:**
```tsx
// RIGHT: Max-width on paragraph containers (50-75ch ideal, 65ch default)
Body copy with constrained line length and proper line height.
// RIGHT: Heading gets tighter line height
Page Heading
Section Title
// RIGHT: Inline links always underlined
Inline link
```
### Type Scale (Tailwind — modular, 1.25 Major Third ratio)
```css
/* In your global CSS or @theme block */
@theme {
--font-size-xs: 0.64rem; /* ~10px */
--font-size-sm: 0.8rem; /* ~13px */
--font-size-base: 1rem; /* 16px */
--font-size-lg: 1.25rem; /* ~20px */
--font-size-xl: 1.563rem; /* ~25px */
--font-size-2xl: 1.953rem; /* ~31px */
--font-size-3xl: 2.441rem; /* ~39px */
}
```
### Threshold Reference
| Property | Threshold | Notes |
|----------|-----------|-------|
| Line length — print | 50–75 ch | Use `max-w-prose` (65ch) |
| Line length — screen | 60–100 ch | UI panels can go wider |
| Line height — body | 1.4–1.6× | `leading-relaxed` = 1.625 |
| Line height — headings | 1.2–1.3× | `leading-tight` = 1.25 |
| Line height — minimum | 1.2× | Never below this |
| Font weight — body | 400 (regular) | `font-normal` |
| Font weight — emphasis | 600+ (semibold) | `font-semibold` minimum |
| Font weight — headings | 700 (bold) | `font-bold` |
| Font size units | rem only | Never em for font-size |
### Key Decisions
| Decision | Recommendation |
|----------|----------------|
| Font size units | rem only — em cascades multiplicatively |
| Line length | `max-w-prose` (65ch) on all paragraph containers |
| Link underlines | Always underlined for inline links — no exceptions |
| Type scale | Derive all sizes from a modular scale ratio (1.25 or 1.333) |
| UI font | Sans-serif for UI chrome; proportional serif optional for long-form |
### Design visual hierarchy using weight, contrast, and spatial relationships — not color alone — HIGH
## Visual Hierarchy & Layout
**Incorrect — competing primaries and flat hierarchy:**
```tsx
// WRONG: Two primary buttons side-by-side (creates decision paralysis)
// WRONG: Emphasizing everything equally — nothing stands out
Title
Body copy that competes with heading
Label also fighting for attention
```
**Correct — three-tier button hierarchy with de-emphasized secondary:**
```tsx
// RIGHT: One primary CTA. Secondary is outlined. Tertiary is ghost/text.
// RIGHT: De-emphasize secondary content rather than only boosting primary
Page title
Supporting description
Metadata label
```
### Hierarchy Principles
| Principle | Rule | Rationale |
|-----------|------|-----------|
| Button tiers | primary → outline → ghost | One primary per view maximum |
| De-emphasis | Mute secondary content | Easier than boosting everything |
| F/Z scan path | Critical info top-left → right | Matches natural eye movement |
| Von Restorff | Isolate ONE element per view | Uniqueness signals importance |
| Proximity | Group related elements closely | Spacing communicates relationship |
| Max-width | Contain layout, don't fill screen | Prevents unreadable line lengths |
### Layout Rules
```tsx
// RIGHT: Contain content width for readability
{/* Never stretch to 100vw on wide screens */}
// RIGHT: Use deliberate spacing to show/break relationships
{/* Tight = related items */}
{/* Gap = new section */}
```
### Key Decisions
| Decision | Recommendation |
|----------|----------------|
| Grayscale test | Design in grayscale first — hierarchy must work without color |
| Button count | Maximum ONE primary button per view |
| Emphasis strategy | De-emphasize secondary; don't over-emphasize primary |
| Von Restorff | Use isolation sparingly — max one "different" element per view |
| Readability cap | `max-w-prose` or `max-w-4xl` on all content containers |
---
## References (1)
### Ork Delta
# UI Components Skill: OrchestKit Delta
Ork-specific floors, scars, and house decisions for `src/skills/ui-components`.
Vendor mechanics (shadcn/ui install and customization walkthroughs, Radix
primitive API tours, CVA and tailwind-merge tutorials, next-themes setup,
TanStack Table wiring, OKLCH variable listings) are deliberately not restated
here. See the section "Upstream coverage (do not restate)" in SKILL.md for the
first-party source that owns each removed topic.
## Wrap shadcn components; never edit the generated files under components/ui
Why: House convention carried since the v2.0 consolidation of shadcn-patterns
and radix-primitives into src/skills/ui-components (metadata.json, Feb 2026).
Upstream treats generated component files as yours to edit; ork forbids it
(this SKILL.md's FORBIDDEN list) because edited generated files silently lose
every fix the next `npx shadcn@latest add` or `apply <style>` would bring, the
same generated-file-drift class this repo guards against in plugins/. The
convention was asserted by the test-cases.json case `shadcn-customization`
until the 2026-07-31 wrap-plus-delta thinning removed the rule file it traced
to. A working wrapper (loading-state Button extension with ref forwarding)
survives in `scripts/extended-button.tsx`.
Upstream: vercel:shadcn (marketplace skill), https://ui.shadcn.com/docs
## Reach for the scripts/ templates before re-deriving wrapper code
Why: House decision from the 2026-07-31 thinning of src/skills/ui-components.
The five deleted reference files (cva-variant-system, component-extension,
aschild-composition, dialog-modal-patterns, dropdown-menu-patterns) each
restated the same Button, Dialog, and DropdownMenu wrappers that already exist
as runnable templates in this skill: `scripts/cva-component.tsx`,
`scripts/extended-button.tsx`, `scripts/custom-dialog.tsx`,
`scripts/custom-dropdown.tsx`, `scripts/composed-trigger.tsx`, and
`scripts/custom-theme.css`. The prose copies had already diverged from the
templates in class lists and ref handling. Keep exactly one copy: the
templates. Use them first, then the upstream docs; never a fresh derivation.
Upstream: context7 /radix-ui/website and https://ui.shadcn.com/docs/components
## Use AlertDialog, never plain Dialog, for destructive confirmations
Why: House test contract since skill v2.0. The test-cases.json case
`radix-dialog` asserted "Uses AlertDialog (not Dialog) for destructive
confirmations" until the 2026-07-31 thinning removed the case with the rule
file it traced to; the decision now lives in this file and in the SKILL.md
Key Decisions table. The scar behind it: Dialog closes on overlay click, so a
stray click confirms nothing but dismisses the guard, while AlertDialog forces
an explicit Cancel or Action choice.
Upstream: https://www.radix-ui.com/primitives/docs/components/alert-dialog
## Keep the skill eval's graded assertions satisfiable from SKILL.md alone
Why: `tests/evals/skills/ui-components.eval.yaml` grades sessions on CVA
variants, cn() merging, asChild composition, Dialog.Title presence, portal
rendering, data-state styling, and OKLCH theming. The 2026-07-31 thinning
deleted the reference files that restated those topics, but the graded
contract did not move: SKILL.md's Quick Start, Key Decisions, and
Anti-Patterns sections must keep carrying enough signal to pass. If this eval
regresses after a future trim, restore signal to SKILL.md; do not resurrect
vendor tutorials.
Upstream: per-topic first-party sources in the SKILL.md section "Upstream coverage (do not restate)"