---
type: skill
domain: architecture
links: [Corpus_Callosum/CONSTITUTION.md, PULSE_OS.md]
---

# UI_ALCHEMIST.md
> **ROLE:** UX/UI DESIGNER
> **TRIGGER:** "MAKE IT PRETTY" / "UI" / "COMPONENT"

## Step-by-Step Protocol
1. **Query existing patterns** — run `brain_query.py --query "UI components design system"`. Check for established spacing, color, and typography decisions.
2. **Define component hierarchy** — Atoms (Button, Input, Label) -> Molecules (SearchBar, FormField) -> Organisms (Header, TaskCard) -> Templates -> Pages. Never skip levels.
3. **Set render budgets** — every component must render in <16ms (60fps). Measure with `React.Profiler` or `performance.mark()`. Break up work exceeding 50ms with `requestIdleCallback`.
4. **Apply accessibility (WCAG 2.1 AA)** — contrast ratio >=4.5:1 for text, >=3:1 for large text. All interactive elements keyboard-navigable. All images have `alt`. All forms have `<label>`.
5. **Mobile-first implementation** — write base CSS for 320px, then `@media (min-width: 768px)` for tablet, `@media (min-width: 1024px)` for desktop. Test on real devices.

## Metrics & Thresholds
- **Render time:** <16ms per frame (60fps), <50ms for initial component mount
- **Contrast ratio:** >=4.5:1 normal text, >=3:1 large text (WCAG 2.1 AA)
- **Lighthouse accessibility score:** >=90
- **Bundle size per component:** <10KB gzipped (atoms), <25KB (molecules), <50KB (organisms)
- **Spacing system:** multiples of 4px only (4, 8, 12, 16, 24, 32, 48, 64)

## Good Example
```tsx
// Atom: accessible button with render budget enforcement
const PulseButton = ({ label, onClick, variant = "primary" }: Props) => {
  // Render budget: this component must mount in <16ms
  return (
    <button
      className={`px-4 py-2 rounded-lg font-medium
        ${variant === "primary" ? "bg-blue-600 text-white" : "bg-gray-200 text-gray-800"}
        focus:ring-2 focus:ring-offset-2 focus:ring-blue-500
        hover:opacity-90 transition-opacity duration-150`}
      onClick={onClick}
      aria-label={label}  /* WCAG: always provide accessible name */
    >
      {label}
    </button>
  );
};
```

## Anti-Patterns
1. **Inline styles over design tokens** — kills consistency; always use spacing/color tokens from the system.
2. **Skipping keyboard navigation** — 15% of users rely on it; every `onClick` needs `onKeyDown` (Enter/Space).
3. **Rendering lists without virtualization** — >50 items causes jank; use `react-window` or `virtuoso` for long lists.

## Tools to Use
- `python pulse/brain/brain_query.py --query "UI design tokens"` — find existing design decisions
- `python pulse/tasks/pulse_relay.py --tasks "Accessibility Audit:architecture:fast"` — delegate a11y sweep
- `python pulse/brain/pulse_save.py --agent ui_alchemist --learnings "what you learned"` — save design decisions

## Verification Checklist
- [ ] All components use 4px spacing grid (no arbitrary values)
- [ ] Render budget met: <16ms per frame, verified with Profiler
- [ ] WCAG 2.1 AA: contrast >=4.5:1, all inputs labeled, keyboard-navigable
- [ ] Component hierarchy follows Atomic Design (atoms -> molecules -> organisms)
- [ ] Mobile-first: base styles at 320px, progressive enhancement upward
