@cubis/foundry 0.3.67 → 0.3.68

package/workflows/skills/frontend-design/commands/adapt.md

@@ -0,0 +1,68 @@
+# /adapt
+
+Make it responsive: mobile-first, fluid scaling, container queries.
+
+## What It Does
+
+Reviews and improves responsive behavior. Ensures the design works across screen sizes using mobile-first CSS, fluid scaling, and modern container queries. Targets real device breakpoints and interaction patterns.
+
+## Responsive Strategy
+
+### Mobile-First Cascade
+
+```css
+/* Base: mobile (320px+) */
+.layout {
+  padding: var(--space-4);
+}
+
+/* Tablet (768px+) */
+@media (min-width: 48em) {
+  .layout {
+    padding: var(--space-6);
+  }
+}
+
+/* Desktop (1024px+) */
+@media (min-width: 64em) {
+  .layout {
+    padding: var(--space-8);
+  }
+}
+```
+
+### Fluid Design
+
+- Use `clamp()` for font sizes, spacing, and widths
+- Size formula: `clamp(min, preferred, max)`
+- Preferred value uses `vi` or `vw` units for viewport-relative scaling
+
+### Container Queries
+
+```css
+.card-container {
+  container-type: inline-size;
+}
+
+@container (min-width: 400px) {
+  .card {
+    flex-direction: row;
+  }
+}
+```
+
+### Adaptation Checklist
+
+- [ ] Navigation collapses to hamburger or bottom nav on mobile
+- [ ] Tables become cards or scrollable on narrow screens
+- [ ] Images scale with `max-width: 100%` and proper `aspect-ratio`
+- [ ] Touch targets are ≥ 44×44px on mobile
+- [ ] Side-by-side layouts stack vertically on mobile
+- [ ] Font sizes remain readable without zooming (≥ 16px body)
+- [ ] Horizontal scroll is eliminated on all breakpoints
+
+## Usage
+
+- `/adapt` — make the component fully responsive
+- `/adapt mobile` — optimize specifically for mobile
+- `/adapt tablet` — optimize for tablet layout

package/workflows/skills/frontend-design/commands/animate.md

@@ -0,0 +1,85 @@
+# /animate
+
+Add or improve motion: entrances, transitions, loading states.
+
+## What It Does
+
+Adds purposeful animation to the UI. Every animation must serve a function — guiding attention, showing relationships, or providing feedback. Never animate for decoration alone.
+
+## Motion Principles
+
+1. **Functional, not decorative** — animation explains spatial relationships or state changes
+2. **Fast by default** — 150–250ms for micro-interactions, 300–500ms for layout changes
+3. **Ease appropriately** — ease-out for entrances, ease-in for exits, ease-in-out for transitions
+4. **Respect preferences** — always wrap in `@media (prefers-reduced-motion: no-preference)`
+
+## Animation Recipes
+
+### Entrance
+
+```css
+@keyframes fade-in-up {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+.enter {
+  animation: fade-in-up 300ms ease-out both;
+}
+```
+
+### Staggered List
+
+```css
+.list-item {
+  animation: fade-in-up 300ms ease-out both;
+  animation-delay: calc(var(--i) * 60ms);
+}
+```
+
+### Expand/Collapse
+
+```css
+.collapsible {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 300ms ease-in-out;
+}
+.collapsible[open] {
+  grid-template-rows: 1fr;
+}
+.collapsible > * {
+  overflow: hidden;
+}
+```
+
+### Skeleton Loading
+
+```css
+.skeleton {
+  background: linear-gradient(
+    90deg,
+    var(--gray-3) 25%,
+    var(--gray-2) 50%,
+    var(--gray-3) 75%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+@keyframes shimmer {
+  to {
+    background-position: -200% 0;
+  }
+}
+```
+
+## Usage
+
+- `/animate` — add appropriate motion to the component
+- `/animate entrance` — add entrance animations
+- `/animate loading` — add loading state animations

package/workflows/skills/frontend-design/commands/audit.md

@@ -0,0 +1,53 @@
+# /audit
+
+Run technical quality checks on a page or component.
+
+## What It Does
+
+Performs a systematic audit checking accessibility, performance, and responsive behavior. Produces actionable findings with severity and specific fix recommendations.
+
+## Checklist
+
+### Accessibility
+
+- [ ] Color contrast meets WCAG 2.1 AA (4.5:1 text, 3:1 UI)
+- [ ] All images have meaningful alt text
+- [ ] Interactive elements are keyboard-navigable
+- [ ] Focus indicators are visible
+- [ ] ARIA attributes are correct and present where needed
+- [ ] Heading hierarchy is logical (no skipped levels)
+- [ ] Form inputs have associated labels
+
+### Performance
+
+- [ ] Images are appropriately sized and use modern formats (WebP/AVIF)
+- [ ] Fonts are preloaded and use `font-display: swap`
+- [ ] No render-blocking resources in the critical path
+- [ ] Animations use transform/opacity only (GPU-friendly)
+- [ ] No layout shifts from unsized images or dynamic content
+
+### Responsive
+
+- [ ] Content readable at 320px without horizontal scroll
+- [ ] Touch targets ≥ 44px on mobile
+- [ ] No text smaller than 16px on mobile
+- [ ] Navigation accessible at all breakpoints
+- [ ] Images scale correctly with preserved aspect ratios
+
+## Output Format
+
+```
+🔴 CRITICAL — [Issue] at [location]
+   Fix: [specific recommendation]
+
+🟡 WARNING — [Issue] at [location]
+   Fix: [specific recommendation]
+
+🟢 PASS — [What was checked and passed]
+```
+
+## Usage
+
+- `/audit` — audit the entire page
+- `/audit header` — audit only the header section
+- `/audit forms` — audit form accessibility specifically

package/workflows/skills/frontend-design/commands/bolder.md

@@ -0,0 +1,42 @@
+# /bolder
+
+Increase visual impact: stronger typography, bolder colors, more contrast.
+
+## What It Does
+
+Dials up the visual intensity of the design. Makes headlines more commanding, colors more saturated, spacing more dramatic, and overall presence more confident. Use when a design feels timid or forgettable.
+
+## Boldness Techniques
+
+### Typography
+
+- Increase headline weight to 700–900
+- Increase headline size by 1–2 steps on the type scale
+- Add more contrast between heading and body sizes (ratio ≥ 1.5x)
+- Consider a display or condensed font for primary headings
+
+### Color
+
+- Increase chroma/saturation on accent colors
+- Darken text colors for stronger readability
+- Add bold background sections to break visual monotony
+- Use color blocking — full-width colored bands
+
+### Layout
+
+- Increase padding and margins — generous whitespace amplifies boldness
+- Use larger images and media
+- Make CTAs bigger and more prominent
+- Add dramatic scale contrast between elements
+
+### Contrast
+
+- Push light/dark contrast further
+- Use reversed sections (dark background, light text) for emphasis
+- Increase border weight on key elements
+
+## Usage
+
+- `/bolder` — make the entire design more impactful
+- `/bolder typography` — focus on type hierarchy
+- `/bolder hero` — make the hero section commanding

package/workflows/skills/frontend-design/commands/clarify.md

@@ -0,0 +1,34 @@
+# /clarify
+
+Improve information architecture: labels, grouping, wayfinding.
+
+## What It Does
+
+Reviews the UI for clarity issues. Ensures users can quickly understand where they are, what they can do, and what will happen when they act. Focuses on labels, grouping, navigation cues, and information scent.
+
+## Clarity Checks
+
+### Labels & Copy
+
+- Button labels describe the outcome, not the action (`Save Changes` not `Submit`)
+- Form labels are unambiguous — no jargon without context
+- Placeholder text supplements labels, never replaces them
+- Error messages explain what happened AND how to fix it
+
+### Grouping & Structure
+
+- Related items are visually grouped (proximity, borders, backgrounds)
+- Sections have clear headings that orient the user
+- Lists and grids follow a logical order (alphabetical, chronological, by importance)
+
+### Wayfinding
+
+- Current location is always visible (breadcrumbs, active nav state)
+- Navigation labels match destination page headings
+- Users can always get back (back button, breadcrumbs, escape hatch)
+
+## Usage
+
+- `/clarify` — review entire page for clarity
+- `/clarify labels` — fix button/form label issues
+- `/clarify navigation` — improve wayfinding

package/workflows/skills/frontend-design/commands/colorize.md

@@ -0,0 +1,61 @@
+# /colorize
+
+Rework the color palette: harmonies, contrast, dark mode, semantic tokens.
+
+## What It Does
+
+Evaluates and improves the color system. Generates harmonious palettes using OKLCH, ensures sufficient contrast, builds semantic color tokens, and creates dark mode variants.
+
+## Color Workflow
+
+### 1. Audit Current Palette
+
+- List all unique colors in the codebase
+- Check contrast ratios against WCAG 2.2 AA
+- Identify redundant or near-duplicate colors
+
+### 2. Build Semantic Tokens
+
+```css
+:root {
+  /* Surface */
+  --color-surface-primary: oklch(98% 0.005 250);
+  --color-surface-secondary: oklch(95% 0.008 250);
+  --color-surface-elevated: oklch(100% 0 0);
+
+  /* Text */
+  --color-text-primary: oklch(20% 0.02 250);
+  --color-text-secondary: oklch(45% 0.02 250);
+  --color-text-muted: oklch(60% 0.01 250);
+
+  /* Interactive */
+  --color-interactive-primary: oklch(55% 0.18 250);
+  --color-interactive-hover: oklch(48% 0.18 250);
+  --color-interactive-active: oklch(42% 0.18 250);
+
+  /* Feedback */
+  --color-success: oklch(55% 0.15 145);
+  --color-warning: oklch(70% 0.15 80);
+  --color-error: oklch(55% 0.2 25);
+  --color-info: oklch(55% 0.15 250);
+}
+```
+
+### 3. Dark Mode
+
+- Swap lightness values — don't just invert
+- Reduce chroma slightly in dark mode to avoid glowing
+- Test contrast ratios in both modes
+
+### 4. Apply the 60-30-10 Rule
+
+- 60% dominant (surface/background)
+- 30% secondary (cards, sections, nav)
+- 10% accent (CTAs, highlights, active states)
+
+## Usage
+
+- `/colorize` — full color system review and rebuild
+- `/colorize dark-mode` — create or fix dark mode
+- `/colorize contrast` — fix contrast issues only
+- `/colorize tokens` — extract hardcoded colors into tokens

package/workflows/skills/frontend-design/commands/critique.md

@@ -0,0 +1,26 @@
+# /critique
+
+UX design review focused on hierarchy, clarity, emotional resonance, and user flow.
+
+## What It Does
+
+Evaluates the design from a user's perspective. Assesses whether the interface communicates clearly, guides attention effectively, and creates the right emotional response.
+
+## Review Areas
+
+1. **Visual hierarchy** — Is there a clear reading order? Does the most important content stand out?
+2. **Clarity** — Can a first-time user understand what to do within 5 seconds?
+3. **Emotional resonance** — Does the design create the intended feeling? (trust, excitement, calm, urgency)
+4. **User flow** — Is the path from entry to goal obvious and frictionless?
+5. **Differentiation** — Does it look distinctive or generic? Would a user remember it?
+6. **Consistency** — Are patterns consistent throughout? Same action = same look?
+
+## Output Format
+
+Rate each area (Strong / Adequate / Needs Work), then provide 3-5 specific, actionable improvements prioritized by impact.
+
+## Usage
+
+- `/critique` — full UX review
+- `/critique hero` — critique just the hero section
+- `/critique checkout flow` — critique the checkout user flow

package/workflows/skills/frontend-design/commands/delight.md

@@ -0,0 +1,49 @@
+# /delight
+
+Add moments of surprise: easter eggs, playful copy, unexpected polish.
+
+## What It Does
+
+Adds small moments of joy and personality to the interface. These are intentional touches that make users smile without getting in the way of tasks. Delight is the layer you add after everything works flawlessly.
+
+## Delight Patterns
+
+### Micro-Interactions
+
+- Confetti or sparkle on successful completion of a milestone
+- Subtle bounce on button click
+- Progress bar with personality (color changes, celebratory state at 100%)
+- Checkbox with a satisfying check animation
+
+### Copy & Personality
+
+- Playful empty states ("Nothing here yet — let's change that")
+- Varied success messages instead of generic "Done!"
+- Personality-appropriate loading messages
+- Friendly 404 pages with helpful navigation
+
+### Visual Surprises
+
+- Hover effects that reveal hidden details
+- Smooth page transitions that feel intentional
+- Seasonal or contextual theme touches (subtle, toggleable)
+- Cursor effects on special pages (use very sparingly)
+
+### Feedback & Celebration
+
+- Achievement unlocked patterns for onboarding milestones
+- Progress visualization that feels rewarding
+- Sound design cues (optional, off by default, never auto-play)
+
+## Rules
+
+1. Never delay the user — delight happens alongside or after the task
+2. Never repeat the same delight — vary or suppress after first encounter
+3. Respect `prefers-reduced-motion` — skip or simplify animations
+4. Keep it subtle — if the user notices it consciously every time, it's too much
+
+## Usage
+
+- `/delight` — add moments of delight to the current component
+- `/delight empty-states` — make empty states friendlier
+- `/delight completion` — add celebration on task completion

package/workflows/skills/frontend-design/commands/distill.md

@@ -0,0 +1,29 @@
+# /distill
+
+Simplify the UI: remove clutter, reduce cognitive load, clarify hierarchy.
+
+## What It Does
+
+Identifies unnecessary complexity in the interface and removes it. Focuses on content hierarchy, reducing visual noise, and ensuring every element earns its place on screen.
+
+## Simplification Principles
+
+1. **Remove before restyle** — if an element doesn't serve a clear purpose, remove it
+2. **Reduce visual weight** — lighter borders, fewer colors, quieter backgrounds
+3. **Merge related elements** — combine redundant labels, consolidate actions
+4. **Strengthen hierarchy** — make the primary action obvious at a glance
+5. **Increase whitespace** — give remaining elements room to breathe
+
+## What to Look For
+
+- Redundant labels or headings
+- Too many competing calls-to-action
+- Visual elements that don't communicate information
+- Overly complex layouts that could be flattened
+- Decorative elements that add noise without meaning
+
+## Usage
+
+- `/distill` — simplify the entire view
+- `/distill navigation` — simplify navigation structure
+- `/distill form` — reduce form complexity

package/workflows/skills/frontend-design/commands/extract.md

@@ -0,0 +1,43 @@
+# /extract
+
+Pull reusable patterns into components, tokens, or utilities.
+
+## What It Does
+
+Identifies repeated patterns in the codebase and extracts them into reusable abstractions: design tokens, utility classes, shared components, or composable hooks.
+
+## Extraction Targets
+
+### Design Tokens
+
+- Repeated color values → CSS custom properties
+- Repeated spacing values → spacing scale tokens
+- Repeated font sizes → type scale tokens
+- Repeated shadows, radii, transitions → effect tokens
+
+### Components
+
+- Repeated markup patterns → shared components
+- Similar-but-different components → unified component with variants
+- Complex inline styles → styled component or utility composition
+
+### Utilities
+
+- Repeated layout patterns → utility classes or layout components
+- Repeated responsive patterns → shared breakpoint utilities
+- Repeated animation patterns → shared keyframes or transition utilities
+
+## Extraction Process
+
+1. **Scan** — identify repeated patterns across the codebase
+2. **Group** — cluster similar patterns and find the canonical version
+3. **Name** — choose clear, intention-revealing names
+4. **Extract** — create the abstraction with appropriate API
+5. **Replace** — update all usage sites to reference the shared abstraction
+6. **Verify** — visual regression check that nothing changed
+
+## Usage
+
+- `/extract` — scan and extract all reusable patterns
+- `/extract tokens` — extract design tokens only
+- `/extract components` — extract repeated markup into components

package/workflows/skills/frontend-design/commands/harden.md

@@ -0,0 +1,51 @@
+# /harden
+
+Strengthen accessibility: ARIA, keyboard nav, screen reader support, contrast.
+
+## What It Does
+
+Reviews code for accessibility violations and hardens it to WCAG 2.2 AA standards. Covers semantic HTML, ARIA usage, keyboard navigation, screen reader announcements, and color contrast.
+
+## Accessibility Checklist
+
+### Semantic HTML
+
+- Use `<button>` for actions, `<a>` for navigation — never `<div onclick>`
+- Use heading hierarchy (`h1` → `h2` → `h3`) without skipping levels
+- Use `<nav>`, `<main>`, `<aside>`, `<footer>` landmarks
+- Lists use `<ul>`/`<ol>`, not styled `<div>` sequences
+
+### ARIA
+
+- Prefer native HTML semantics over ARIA — `<button>` over `role="button"`
+- Dynamic content uses `aria-live` regions (polite for updates, assertive for errors)
+- Modals trap focus and use `aria-modal="true"` + `role="dialog"`
+- Custom widgets have appropriate `role`, `aria-label`, and state attributes
+
+### Keyboard Navigation
+
+- All interactive elements are reachable via Tab
+- Tab order matches visual order (no positive `tabindex`)
+- Escape closes modals/dropdowns and returns focus to trigger
+- Arrow keys navigate within composite widgets (tabs, menus, radio groups)
+- Skip-to-content link is the first focusable element
+
+### Color & Contrast
+
+- Text contrast ratio ≥ 4.5:1 (normal text), ≥ 3:1 (large text, 18px+ or 14px+ bold)
+- UI component contrast ≥ 3:1 against adjacent colors
+- Information is never conveyed by color alone — use icons, patterns, or text
+
+### Forms
+
+- Every input has a visible `<label>` (or `aria-label` for icon-only inputs)
+- Required fields use `aria-required="true"` and visible indicator
+- Error messages are linked to inputs via `aria-describedby`
+- Form submission errors announce via `aria-live` region
+
+## Usage
+
+- `/harden` — full accessibility audit
+- `/harden keyboard` — keyboard navigation only
+- `/harden contrast` — color contrast check only
+- `/harden forms` — form accessibility only

package/workflows/skills/frontend-design/commands/normalize.md

@@ -0,0 +1,21 @@
+# /normalize
+
+Align with design system standards: tokens, spacing, typography consistency.
+
+## What It Does
+
+Reviews code for inconsistencies with the project's design system. Replaces hardcoded values with tokens, normalizes spacing to the grid, and enforces typographic consistency.
+
+## Checks
+
+- Replace hardcoded colors with design tokens / CSS custom properties
+- Replace hardcoded spacing with spacing scale values
+- Normalize font sizes to the type scale
+- Ensure consistent border-radius, shadow, and transition values
+- Verify component naming follows project conventions
+
+## Usage
+
+- `/normalize` — normalize the entire file
+- `/normalize colors` — fix only color inconsistencies
+- `/normalize spacing` — fix only spacing values

package/workflows/skills/frontend-design/commands/onboard.md

@@ -0,0 +1,58 @@
+# /onboard
+
+Design first-run experience: empty states, progressive disclosure, guided tours.
+
+## What It Does
+
+Reviews and improves the first-time user experience. Focuses on what users see before they have any data, how they learn the interface, and how they reach their first moment of value.
+
+## First-Run Patterns
+
+### Empty States
+
+Every empty state should include:
+
+1. **Illustration or icon** — visual context (not a blank void)
+2. **Headline** — what this area is for
+3. **Description** — why it's empty and what to do next
+4. **Primary action** — one clear CTA to get started
+
+```
+┌──────────────────────────────┐
+│         [illustration]       │
+│                              │
+│     No projects yet          │
+│                              │
+│  Create your first project   │
+│  to start tracking work.     │
+│                              │
+│     [ Create Project ]       │
+└──────────────────────────────┘
+```
+
+### Progressive Disclosure
+
+- Show only essential features on first use
+- Reveal advanced features as users demonstrate readiness
+- Use contextual tooltips (not modal tours) to explain features in context
+- Let users dismiss guidance permanently
+
+### Onboarding Checklist
+
+- Show progress toward setup completion (3/5 steps done)
+- Make steps completable in any order when possible
+- Celebrate completion with a moment of delight
+- Auto-dismiss the checklist once all steps are done
+
+### Guided Walkthrough
+
+- Maximum 3–5 steps — fewer is better
+- Each step highlights one feature with one sentence
+- Allow skipping at any point
+- Never block the user from using the app
+
+## Usage
+
+- `/onboard` — review and improve first-run experience
+- `/onboard empty-states` — design empty states for all views
+- `/onboard checklist` — create setup completion checklist

package/workflows/skills/frontend-design/commands/optimize.md

@@ -0,0 +1,49 @@
+# /optimize
+
+Improve rendering performance: layout shifts, paint costs, asset loading.
+
+## What It Does
+
+Reviews frontend code for performance issues that affect perceived speed and visual stability. Targets layout shifts, expensive paint operations, unoptimized assets, and render-blocking patterns.
+
+## Performance Targets
+
+| Metric | Good    | Needs Work |
+| ------ | ------- | ---------- |
+| LCP    | < 2.5s  | > 4.0s     |
+| CLS    | < 0.1   | > 0.25     |
+| INP    | < 200ms | > 500ms    |
+
+## Checklist
+
+### Layout Stability
+
+- Images and embeds have explicit `width`/`height` or `aspect-ratio`
+- Fonts use `font-display: swap` with size-adjusted fallbacks
+- Dynamic content reserves space before loading
+
+### Paint Performance
+
+- Animations use `transform`/`opacity` only (compositor-friendly)
+- Avoid animating `width`, `height`, `top`, `left`, `margin`, `padding`
+- Use `will-change` sparingly and only on elements about to animate
+- Avoid `filter: blur()` on large areas
+
+### Asset Loading
+
+- Images use modern formats (WebP, AVIF) with `<picture>` fallback
+- Above-fold images use `loading="eager"`, below-fold use `loading="lazy"`
+- Critical CSS is inlined; non-critical is deferred
+- Fonts are preloaded with `<link rel="preload">`
+
+### Rendering
+
+- Reduce DOM depth — flatten unnecessary wrapper elements
+- Use CSS containment (`contain: layout style paint`) on isolated components
+- Virtualize long lists (> 100 items)
+
+## Usage
+
+- `/optimize` — full performance review
+- `/optimize images` — focus on image loading
+- `/optimize animations` — focus on animation performance