@cubis/foundry 0.3.67 → 0.3.69

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/commands/polish.md

@@ -0,0 +1,39 @@
+# /polish
+
+Refine visual details: shadows, borders, transitions, micro-interactions.
+
+## What It Does
+
+Elevates the design from "functional" to "finished". Focuses on the details that make interfaces feel premium: consistent shadows, refined borders, smooth transitions, and subtle micro-interactions.
+
+## Refinement Areas
+
+### Shadows & Depth
+
+- Layer shadows for realism (combine ambient + direct)
+- Scale shadow intensity with elevation
+- Use `box-shadow` with multiple values, not single flat shadows
+
+### Borders & Dividers
+
+- Prefer subtle tinted borders over hard gray lines
+- Use border-color that adapts to light/dark mode
+- Consider removing borders in favor of spacing or background contrast
+
+### Transitions
+
+- Add `transition` to interactive elements (buttons, links, cards)
+- Use appropriate duration (150–250ms for micro, 300–500ms for layout)
+- Match easing to the interaction type
+
+### Micro-Interactions
+
+- Hover states that provide feedback without distraction
+- Focus indicators that are visible but not overwhelming
+- Active/pressed states for tactile feedback
+
+## Usage
+
+- `/polish` — polish the entire component
+- `/polish shadows` — refine shadows only
+- `/polish transitions` — add or improve transitions

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/commands/quieter.md

@@ -0,0 +1,43 @@
+# /quieter
+
+Reduce visual noise: softer colors, lighter weights, more whitespace.
+
+## What It Does
+
+Dials down the visual intensity. Makes the design calmer, more refined, and easier on the eyes. Reduces competing elements so content can speak. Use when a design feels loud, cluttered, or overwhelming.
+
+## Quieting Techniques
+
+### Typography
+
+- Reduce heading weight to 500–600 (medium/semibold)
+- Decrease size contrast between headings and body
+- Increase line-height for more breathing room
+- Use a lighter text color for secondary content
+
+### Color
+
+- Reduce chroma/saturation across the palette
+- Use tinted grays instead of pure gray
+- Limit accent color usage to one or two key elements
+- Soften borders from solid to subtle tints
+
+### Layout
+
+- Increase whitespace between sections
+- Reduce the number of visual elements per viewport
+- Remove decorative elements that don't serve a purpose
+- Use subtle dividers (thin lines, spacing) instead of heavy borders
+
+### Visual Weight
+
+- Replace filled icons with outlined variants
+- Use lighter box-shadows or remove them entirely
+- Reduce image saturation or apply subtle overlays
+- Soften corner radii (sharp corners feel louder)
+
+## Usage
+
+- `/quieter` — make the entire design calmer
+- `/quieter colors` — desaturate and soften the palette
+- `/quieter layout` — add breathing room and reduce density

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/commands/teach-impeccable.md

@@ -0,0 +1,41 @@
+# /teach-impeccable
+
+Explain design rationale: why a decision was made, what principle it follows.
+
+## What It Does
+
+Teaches the user about design principles by explaining the reasoning behind specific design decisions in the current codebase. Connects implementation choices to underlying principles from typography, color theory, spatial design, motion, accessibility, and UX psychology.
+
+## Teaching Format
+
+For each design decision explained:
+
+1. **What** — the specific design choice in the code
+2. **Why** — the principle or research behind it
+3. **Reference** — link to the relevant reference file
+4. **Alternative** — what would happen if a different choice were made
+
+## Example Response
+
+> **What**: The body font size is set to `clamp(1rem, 0.95rem + 0.25vi, 1.125rem)`
+>
+> **Why**: Fluid typography scales smoothly between screen sizes without breakpoints. The minimum of 16px ensures readability on mobile, while 18px on desktop improves reading comfort for longer content. This follows the fluid type scale principle from `references/typography.md`.
+>
+> **Alternative**: Using fixed `font-size: 16px` would require manual breakpoint adjustments and creates a jarring size jump at each threshold.
+
+## Topics You Can Ask About
+
+- Why a specific color was chosen
+- Why spacing values follow a particular scale
+- Why an animation uses a specific duration or easing
+- Why a layout uses CSS Grid vs Flexbox
+- Why a component is structured a certain way
+- Why an accessibility pattern was implemented
+- Any design decision in the current codebase
+
+## Usage
+
+- `/teach-impeccable` — explain key design decisions in the current file
+- `/teach-impeccable color` — explain color choices
+- `/teach-impeccable typography` — explain type scale decisions
+- `/teach-impeccable spacing` — explain spatial design choices

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/evals/evals.json

@@ -0,0 +1,75 @@
+{
+  "skill": "frontend-design",
+  "version": "3.0",
+  "evals": [
+    {
+      "id": "landing-page-editorial",
+      "prompt": "Build a landing page for a developer tool called 'Forge' — make it feel premium and editorial, not like every other SaaS template.",
+      "assertions": [
+        "Uses a distinctive font pairing (not Inter, Roboto, or Arial as primary)",
+        "Has a clear visual hierarchy with varied spacing",
+        "Does not use a bento grid or hero split 50/50 layout",
+        "Color palette avoids purple-to-blue gradients and neon-on-dark",
+        "Includes responsive design considerations",
+        "HTML is semantic with proper heading hierarchy"
+      ]
+    },
+    {
+      "id": "dashboard-redesign",
+      "prompt": "Redesign this admin dashboard. It currently uses gray cards on white background with Inter font. Make it distinctive.",
+      "assertions": [
+        "Changes the font from Inter to something more distinctive",
+        "Breaks away from uniform card grid layout",
+        "Uses tinted neutrals instead of pure gray",
+        "Creates visual rhythm through varied spacing",
+        "Maintains data readability while improving aesthetics",
+        "Passes the AI Slop Test — does not look generically AI-generated"
+      ]
+    },
+    {
+      "id": "color-system-health",
+      "prompt": "I need a color system for a health tech app. No fintech blue, no AI purple.",
+      "assertions": [
+        "Uses warm earth tones, sage, or soft coral (appropriate for health)",
+        "Avoids deep navy/fintech blue and purple-cyan palette",
+        "Defines semantic colors (success, warning, error) alongside brand",
+        "Includes dark mode considerations",
+        "Specifies contrast ratios for accessibility",
+        "Uses OKLCH or modern color space, not just hex"
+      ]
+    },
+    {
+      "id": "audit-command",
+      "prompt": "/audit this checkout page for accessibility and responsive issues",
+      "assertions": [
+        "Checks color contrast ratios against WCAG 2.1 AA",
+        "Verifies keyboard navigation and focus management",
+        "Tests touch target sizes for mobile",
+        "Reviews form labels and error messages",
+        "Produces actionable findings, not generic advice"
+      ]
+    },
+    {
+      "id": "critique-command",
+      "prompt": "/critique the onboarding flow — is it clear? Does it build trust?",
+      "assertions": [
+        "Evaluates visual hierarchy and user flow",
+        "Assesses trust-building elements",
+        "Reviews empty states and progressive disclosure",
+        "Provides specific, actionable improvement suggestions",
+        "References UX psychology principles where relevant"
+      ]
+    },
+    {
+      "id": "non-technical-user",
+      "prompt": "I'm not a developer. Can you help me design a portfolio website? I want it to feel artsy and warm.",
+      "assertions": [
+        "Explains design choices in plain language without jargon",
+        "Delivers working code, not just design advice",
+        "Chooses an appropriate warm/artsy aesthetic direction",
+        "Provides clear instructions for what to change and customize",
+        "Does not assume the user knows CSS or HTML terminology"
+      ]
+    }
+  ]
+}

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/references/color-and-contrast.md

@@ -0,0 +1,97 @@
+# Color & Contrast Reference
+
+## Color Space
+
+Use OKLCH for perceptually uniform color manipulation. Colors that share the same L (lightness) value actually look equally bright, unlike HSL.
+
+```css
+:root {
+  /* Define palette in OKLCH */
+  --brand-primary: oklch(55% 0.2 250); /* vibrant blue-ish */
+  --brand-accent: oklch(70% 0.18 150); /* green accent */
+  --text-primary: oklch(20% 0.02 250); /* near-black, tinted */
+  --text-secondary: oklch(45% 0.02 250); /* medium gray, tinted */
+  --bg-primary: oklch(98% 0.005 250); /* near-white, tinted */
+  --bg-secondary: oklch(95% 0.01 250); /* subtle off-white */
+}
+```
+
+## The 60-30-10 Rule
+
+Every palette needs a distribution hierarchy:
+
+- **60%** — Dominant (backgrounds, large surfaces)
+- **30%** — Secondary (cards, sections, supporting areas)
+- **10%** — Accent (CTAs, highlights, key interactive elements)
+
+Dominant colors with sharp accents outperform timid, evenly distributed palettes.
+
+## Tinted Neutrals
+
+Never use pure gray. Always tint neutrals toward the brand hue:
+
+```css
+/* Instead of gray-500: hsl(0, 0%, 50%) */
+/* Use brand-tinted neutral: */
+--neutral-500: oklch(55% 0.015 250); /* 250 = brand hue */
+```
+
+Even a 1-2% chroma hint creates subconscious cohesion. The user won't notice the tint — they'll just feel the palette is "professional."
+
+## Dark Mode
+
+Do not simply invert lightness. Dark mode requires its own decisions:
+
+1. Use elevated surfaces (slightly lighter) instead of borders to create hierarchy
+2. Reduce chroma — highly saturated colors on dark backgrounds cause eye strain
+3. Use a dark background between 15-20% lightness (not pure black)
+4. Increase font weight by one step (light → regular, regular → medium)
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-primary: oklch(15% 0.01 250);
+    --bg-secondary: oklch(20% 0.015 250);
+    --text-primary: oklch(92% 0.01 250);
+    --text-secondary: oklch(70% 0.015 250);
+    --brand-primary: oklch(70% 0.15 250); /* reduced chroma */
+  }
+}
+```
+
+Or use the `light-dark()` function:
+
+```css
+:root {
+  color-scheme: light dark;
+  --bg: light-dark(oklch(98% 0.005 250), oklch(15% 0.01 250));
+}
+```
+
+## Contrast Ratios (WCAG 2.1 AA)
+
+| Element                            | Minimum ratio | Check                            |
+| ---------------------------------- | ------------- | -------------------------------- |
+| Normal text (< 18px)               | 4.5:1         | Body copy, labels, descriptions  |
+| Large text (≥ 18px bold or ≥ 24px) | 3:1           | Headings, large buttons          |
+| UI components                      | 3:1           | Borders, icons, focus indicators |
+| Non-text contrast                  | 3:1           | Charts, data visualizations      |
+
+## Color Psychology by Context
+
+| Context              | Approach                                                               | Avoid                                       |
+| -------------------- | ---------------------------------------------------------------------- | ------------------------------------------- |
+| Finance / Banking    | Deep navy, forest green, gold accents. Trust = desaturation.           | Bright red (danger), neon anything          |
+| Health / Wellness    | Sage, warm earth tones, soft coral. Calming = low chroma.              | Clinical white, cold blue                   |
+| Developer tools      | Any bold direction works. Own the choice.                              | Fintech blue, AI purple-cyan                |
+| E-commerce           | Neutral base, single strong accent for CTAs                            | Rainbow — competing accents kill conversion |
+| Creative / Portfolio | Match the work. The palette should feel authored.                      | Generic gradients that override the content |
+| SaaS / Dashboard     | Functional neutrals, semantic color for status (success/warning/error) | Decorative color that competes with data    |
+
+## Anti-Patterns
+
+- Gray text on colored backgrounds — washed out. Use a tinted shade of the background.
+- Pure black (#000) on pure white (#fff) — harsh. Tint both.
+- Purple-to-blue gradients — the default AI palette.
+- Neon on dark with glow effects — screams "AI generated."
+- Gradient text for "impact" on metrics/headings — decorative, not meaningful.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/references/interaction-design.md

@@ -0,0 +1,106 @@
+# Interaction Design Reference
+
+## Form Design
+
+1. **Labels above inputs** — always visible, never placeholder-only labels
+2. **Inline validation** — validate on blur, not on every keystroke
+3. **Error placement** — show error text below the field, highlighted in red with an icon
+4. **Success confirmation** — subtle check or green border, not a modal
+5. **Field grouping** — logical sections with clear headers (Personal, Payment, Shipping)
+6. **Smart defaults** — pre-fill when possible (country from locale, email domain suggestions)
+
+```css
+/* Input states */
+.input {
+  border: 1.5px solid var(--border-default);
+}
+.input:focus {
+  border-color: var(--brand-primary);
+  box-shadow: 0 0 0 3px var(--brand-primary-alpha-15);
+  outline: none;
+}
+.input:invalid:blur {
+  border-color: var(--color-error);
+}
+.input:valid {
+  border-color: var(--color-success);
+}
+```
+
+## Focus Management
+
+1. **Visible focus indicators** — never remove `:focus-visible` outlines without providing a better alternative
+2. **Focus trapping** — trap focus in modals, dialogs, and drawers
+3. **Focus restoration** — return focus to trigger element when closing overlays
+4. **Skip links** — provide "Skip to main content" for keyboard users
+
+```css
+:focus-visible {
+  outline: 2px solid var(--brand-primary);
+  outline-offset: 2px;
+}
+/* Remove default only when custom is provided */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+## Loading Patterns
+
+| Pattern           | When to use                        | When NOT to use               |
+| ----------------- | ---------------------------------- | ----------------------------- |
+| Skeleton screen   | Content-heavy pages, initial loads | Simple actions, small updates |
+| Inline spinner    | Button actions, small areas        | Full-page loads               |
+| Progress bar      | File uploads, multi-step processes | Unknown duration              |
+| Optimistic update | Toggle, like, bookmark             | Destructive actions           |
+| Backdrop overlay  | Modal operations                   | Background tasks              |
+
+Loading buttons should:
+
+- Show a spinner replacing the label or beside it
+- Disable the button to prevent double-submission
+- Keep the button the same width (no layout shift)
+
+## Progressive Disclosure
+
+Start simple, reveal complexity through interaction:
+
+1. **Progressive forms** — show basic options first, "Advanced settings" expandable
+2. **Hover reveals** — secondary actions appear on hover (with keyboard alternative)
+3. **Drill-down** — master list → detail view, not everything on one screen
+4. **Contextual toolbars** — show relevant actions based on selection
+5. **Smart defaults with override** — choose the best default, let users change it
+
+## Empty States
+
+Empty states are teaching moments, not dead ends:
+
+- **Explain** what this space is for
+- **Guide** the user to their first action
+- **Illustrate** with a relevant visual (not a generic sad-face icon)
+- **Provide a CTA** — one clear primary action
+
+Bad: "No items found." / Good: "No projects yet. Create your first project to get started."
+
+## Toast / Notification Patterns
+
+1. **Placement** — bottom-center or top-right (don't stack more than 3)
+2. **Timing** — auto-dismiss success after 4-5 seconds, persist errors until dismissed
+3. **Actions** — include "Undo" for destructive operations
+4. **Accessibility** — use `role="status"` or `aria-live="polite"` for non-critical, `role="alert"` for errors
+
+## Hover & Touch Considerations
+
+- Don't hide essential actions behind hover — they're invisible on touch devices
+- Touch targets: minimum 44×44px (iOS) or 48×48dp (Android)
+- Provide touch alternatives for all hover interactions (long-press, swipe, tap-to-reveal)
+- `@media (hover: hover)` — use to gate hover-only interactions
+
+## Anti-Patterns
+
+- Placeholder-only labels — disappear when typing, fail accessibility
+- Modals for simple confirmations — use inline confirmation instead
+- Double-confirm dialogs — "Are you sure?" + "Are you really sure?"
+- Disabled buttons without explanation — tell the user what's missing
+- Infinite scroll without "back to top" — disorienting
+- Auto-focusing the wrong field — focus the first empty required field

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/references/motion-design.md

@@ -0,0 +1,125 @@
+# Motion Design Reference
+
+## Timing Guidelines
+
+| Animation type                                  | Duration        | Note                     |
+| ----------------------------------------------- | --------------- | ------------------------ |
+| Micro-interaction (button press, toggle)        | 100–200ms       | Fast, snappy feedback    |
+| State transition (expand, collapse, tab switch) | 200–350ms       | Noticeable but not slow  |
+| Entry animation (fade in, slide up)             | 300–500ms       | Gentle, welcoming        |
+| Exit animation                                  | 150–300ms       | Always faster than entry |
+| Page transition                                 | 300–600ms       | Smooth handoff           |
+| Complex orchestration (staggered list)          | 400–800ms total | 50–80ms stagger per item |
+
+Rule: exits should be 30-50% faster than entries. Users want content to leave faster than it arrives.
+
+## Easing Curves
+
+Use exponential easing for natural deceleration:
+
+```css
+/* Preferred curves */
+--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);
+--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+/* Spring-like (for playful UIs only) */
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+```
+
+Never use `linear` for UI motion — it feels mechanical. Never use `ease-in` alone — it accelerates into the stop, which feels unnatural.
+
+Avoid bounce and elastic easing — they feel dated and tacky. Real objects decelerate smoothly.
+
+## What to Animate
+
+**GPU-friendly (transform + opacity only):**
+
+```css
+.element {
+  transition:
+    transform 300ms var(--ease-out-quart),
+    opacity 300ms var(--ease-out-quart);
+  will-change: transform; /* hint, use sparingly */
+}
+```
+
+**Never animate these directly** — they trigger layout recalculation:
+
+- `width`, `height`, `padding`, `margin`, `top`, `left`
+- Use `transform: scale()` or `translate()` instead
+
+**Height animation trick** — use CSS Grid:
+
+```css
+.collapsible {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 350ms var(--ease-out-quart);
+}
+.collapsible.open {
+  grid-template-rows: 1fr;
+}
+.collapsible > .inner {
+  overflow: hidden;
+}
+```
+
+## Staggered Reveals
+
+Focus on one well-orchestrated page load with staggered reveals rather than scattered micro-interactions:
+
+```css
+.stagger-item {
+  opacity: 0;
+  transform: translateY(12px);
+  animation: reveal 500ms var(--ease-out-expo) forwards;
+}
+.stagger-item:nth-child(1) {
+  animation-delay: 0ms;
+}
+.stagger-item:nth-child(2) {
+  animation-delay: 60ms;
+}
+.stagger-item:nth-child(3) {
+  animation-delay: 120ms;
+}
+/* 50-80ms per item, cap at ~6 items then batch the rest */
+```
+
+## Reduced Motion
+
+Always respect user preference:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+For critical state changes (tab switch, panel expand), use a simple crossfade instead of removing all motion.
+
+## Perceived Performance
+
+Motion can make loading feel faster:
+
+1. **Skeleton screens** — show layout structure immediately, fill in content
+2. **Progressive reveal** — show the first visible content immediately, animate in the rest
+3. **Optimistic updates** — animate the change immediately, sync with server in background
+4. **Loading indicators** — use progress bars (deterministic) over spinners (indeterminate) when possible
+
+## Anti-Patterns
+
+- Bounce/elastic easing — feels dated, tacky
+- Animating all properties at once — layout thrashing
+- 1-second+ transitions — feels sluggish
+- Animation for decoration only — motion should communicate state
+- Scroll-jacking — hostile to user control
+- Auto-playing animations that can't be stopped — accessibility violation

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/references/responsive-design.md

@@ -0,0 +1,135 @@
+# Responsive Design Reference
+
+## Mobile-First Approach
+
+Write base styles for mobile, then layer on complexity:
+
+```css
+/* Base: mobile */
+.layout {
+  padding: var(--space-4);
+}
+
+/* Tablet+ */
+@media (min-width: 768px) {
+  .layout {
+    padding: var(--space-8);
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+/* Desktop+ */
+@media (min-width: 1024px) {
+  .layout {
+    grid-template-columns: 1fr 2fr 1fr;
+    max-width: 1200px;
+    margin-inline: auto;
+  }
+}
+```
+
+## Fluid Design
+
+Replace fixed breakpoints with fluid values where possible:
+
+```css
+/* Fluid container */
+.container {
+  width: min(100% - 2rem, 1200px);
+  margin-inline: auto;
+}
+
+/* Fluid typography */
+h1 {
+  font-size: clamp(1.875rem, 1.4rem + 2.4vw, 3rem);
+}
+
+/* Fluid spacing */
+.section {
+  padding-block: clamp(2rem, 1rem + 5vw, 6rem);
+}
+
+/* Fluid grid */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr));
+  gap: clamp(1rem, 0.5rem + 2vw, 2rem);
+}
+```
+
+## Container Queries
+
+Use container queries for component-level responsiveness:
+
+```css
+/* Define container */
+.card-wrapper {
+  container-type: inline-size;
+  container-name: card;
+}
+
+/* Component responds to its container, not viewport */
+@container card (min-width: 400px) {
+  .card {
+    display: grid;
+    grid-template-columns: 200px 1fr;
+    gap: var(--space-4);
+  }
+}
+
+@container card (max-width: 399px) {
+  .card {
+    display: flex;
+    flex-direction: column;
+  }
+  .card img {
+    aspect-ratio: 16/9;
+    object-fit: cover;
+  }
+}
+```
+
+## Breakpoint Strategy
+
+| Name | Width         | Target                      |
+| ---- | ------------- | --------------------------- |
+| xs   | < 480px       | Small phones                |
+| sm   | 480px–767px   | Large phones, small tablets |
+| md   | 768px–1023px  | Tablets, small laptops      |
+| lg   | 1024px–1279px | Laptops, desktops           |
+| xl   | 1280px–1535px | Large desktops              |
+| 2xl  | ≥ 1536px      | Ultra-wide, presentations   |
+
+Prefer fluid design over hard breakpoints. Use breakpoints only when the layout fundamentally changes (e.g., sidebar collapse, navigation switch).
+
+## Adaptation Principles
+
+1. **Adapt, don't amputate** — all functionality should be accessible on all devices. Reorganize, don't remove.
+2. **Touch targets** — minimum 44×44px on mobile. Space interactive elements at least 8px apart.
+3. **Navigation** — mobile: bottom tab bar or hamburger with full-screen overlay. Desktop: persistent sidebar or top nav.
+4. **Data tables** — don't horizontally scroll on mobile. Transform into card layout or priority-column format.
+5. **Images** — serve appropriate sizes with `srcset` and `sizes`. Use `aspect-ratio` to prevent layout shift.
+
+```html
+<img
+  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 600px"
+  src="hero-800.webp"
+  alt="Descriptive alt text"
+  loading="lazy"
+  decoding="async"
+  width="800"
+  height="450"
+/>
+```
+
+## Testing Checklist
+
+- [ ] Content readable without horizontal scroll at 320px
+- [ ] Touch targets ≥ 44px on mobile
+- [ ] No text smaller than 16px on mobile (prevents iOS zoom)
+- [ ] Forms usable with on-screen keyboard (inputs not obscured)
+- [ ] Images scale correctly, aspect ratios preserved
+- [ ] Navigation accessible on all breakpoints
+- [ ] Landscape orientation handled gracefully