---
name: frontend-design
description: "Create frontend interfaces from scratch or restyle existing ones in the consistent Palebright/OdyvaOS visual language: warm editorial minimalism, cream and ink foundations, glass surfaces, rounded geometry, amber AI identity, evidence-led product UI, responsive layouts, accessibility, and purposeful motion. Use for React, Next.js, Tailwind, HTML/CSS, dashboards, marketing pages, forms, product flows, timelines, and reusable component systems, even when no visual reference files are available."
---

# Palebright Frontend Design

Build a complete interface from the rules in this file. Do not require palebright/ or another existing page to begin. Use repository references only to calibrate implementation details when they are available.

The goal is recognizable consistency with enough flexibility for a landing page, dashboard, settings screen, onboarding flow, marketplace, form, or internal tool.

## Design contract

Preserve these invariants on every screen:

1. Start with a warm paper-like canvas, never a default stark white or generic dark theme.
2. Use near-black ink for primary text and actions; keep secondary text quiet and readable.
3. Create depth with translucent white surfaces, thin low-opacity borders, backdrop blur, and soft warm shadows.
4. Use rounded geometry consistently: pills for actions and navigation, medium radii for controls, large radii for cards and hero frames.
5. Use small uppercase editorial labels to establish rhythm and hierarchy.
6. Give the interface one recognizable AI anchor: a warm amber orb, glow, highlight, or status marker.
7. Make evidence and state visible where the product performs work: plan, progress, result, consent, or proof.
8. Use motion only to communicate entry, interaction, progress, or causality. Respect reduced motion.
9. Keep the composition calm. One strong focal point is better than many competing effects.
10. Make the interface usable without relying on color, hover, animation, or decorative imagery.

These choices may vary by task:

- Page density: spacious for marketing, compact for operational dashboards.
- Layout: one-column editorial, split hero, 3-column cards, timeline, table, or application shell.
- Secondary accent: green, yellow, red, blue, or violet only when it communicates state, role, or product meaning.
- Serif typography: optional for a hero or closing statement, never for dense UI.
- Imagery: optional. The layout must still feel Palebright when images are removed.
- Framework: use the existing stack; do not force Next.js, Tailwind, or Framer Motion.

## Token foundation

Use these values as the default design tokens. Tune only when contrast, platform, or product semantics require it.

### Color

- page: #faf9f6
- page-alt: #f5f3ee
- panel: #ffffff at 45-80% opacity
- inset-panel: #f7f7f3
- warm-panel: #fff7e9
- ink: #171714
- ink-soft: #4a4a4a
- ink-muted: #8a8a8a
- line: black at 6-9% opacity
- line-strong: black at 10-14% opacity
- focus: #2b6be4
- ai-amber: #c96b2d
- ai-gold: #f2c77d
- success: #37734a on #eef9f1
- watch: #806a20 on #fffbea
- risk: #a94d3d on #fff0eb
- active-blue: #3b70d6 on #e8f0ff
- active-violet: #7651a5 on #faf7ff
- closing-shell: #202231

Do not introduce a rainbow palette for visual variety. Color should answer one of four questions: What is the surface? What is the state? Which agent or role is active? Where should attention go?

### Typography

- UI family: Inter, system-ui, sans-serif, or the existing product sans.
- Display: 44px mobile; 60-76px desktop; weight 600; line-height about 0.98; tracking about -0.06em.
- Section heading: 30-38px mobile; 36-48px desktop; weight 600; tracking about -0.05em.
- Body: 14-16px; line-height 1.5-1.75; readable measure around 32-42rem.
- Eyebrow: 10-12px; semibold; uppercase; letter spacing 0.16-0.20em.
- Metadata: 9-11px; muted; compact.
- Code and evidence: 12-13px monospace, used only for commands, logs, IDs, and tool output.
- Use sentence case for most UI. Keep labels short. Prefer verbs and outcomes over feature jargon.

### Spacing, shape, and elevation

- Base spacing unit: 4px. Common rhythm: 4, 8, 12, 16, 24, 32, 48, 64.
- Page gutter: 20px mobile, 24px desktop.
- Content width: approximately 1152px / max-w-6xl.
- Control radius: 10-12px.
- Card radius: 20-26px.
- Hero/CTA radius: 28-34px.
- Pill radius: 9999px.
- Touch target: 44px minimum.
- Small shadow: 0 8px 24px rgba(35,31,24,0.05).
- Card shadow: 0 18px 48px rgba(35,31,24,0.08).
- Glass shadow: 0 14px 44px rgba(25,25,20,0.08), plus a subtle white inset highlight.
- Avoid heavy borders, hard black shadows, and frequent one-off radii.

A portable CSS starting point:

    :root {
      --pb-page: #faf9f6;
      --pb-page-alt: #f5f3ee;
      --pb-panel: rgba(255, 255, 255, 0.72);
      --pb-inset: #f7f7f3;
      --pb-ink: #171714;
      --pb-ink-soft: #4a4a4a;
      --pb-ink-muted: #8a8a8a;
      --pb-ai: #c96b2d;
      --pb-focus: #2b6be4;
      --pb-line: rgba(23, 23, 20, 0.07);
      --pb-card-shadow: 0 18px 48px rgba(35, 31, 24, 0.08);
    }

## From-scratch workflow

### 1. Define the job and the visual anchor

Write one sentence describing what the user must accomplish. Select one focal element that expresses that job:

- Marketing: outcome headline plus product visual.
- Dashboard: current status plus next action.
- Form: clear invitation plus trustworthy input card.
- Timeline: current step plus evidence or approval gate.
- Settings: active section plus focused control group.
- Marketplace: category/search plus one featured skill or result.

Do not start by styling buttons. Start with the page job, focal element, content hierarchy, and one meaningful state.

### 2. Select a composition

Choose one composition and commit to it:

- Editorial: centered headline, narrow copy, stacked sections, large whitespace.
- Split: text and action on one side, product/illustration on the other.
- Grid: one lead card plus 2-5 supporting cards.
- Workspace: top bar, primary content, secondary evidence rail.
- Timeline: vertical steps with status, selected detail, and proof.
- Flow: tabs or steps that reveal one state at a time.

Keep the main container aligned across sections. Use one main grid per section. Do not stack unrelated cards into a dashboard simply because cards are easy to build.

### 3. Build the shell before details

Implement these layers in order:

1. Page background with a faint radial light or nearly invisible grid.
2. Header or navigation with clear brand, route, and primary action.
3. Main container and responsive gutters.
4. Section hierarchy with labels, headings, copy, and separators.
5. Focal product surface or interaction.
6. Supporting modules and states.
7. Footer, trust note, or closing action.

A typical marketing shell is: announcement strip, floating nav, hero, visual anchor, proof section, product showcase, capability grid, trust/memory section, closing CTA, footer. Omit sections that do not serve the request.

### 4. Apply the surface language

For any panel or card:

- Use a warm or transparent white surface.
- Add a thin low-opacity border.
- Use a medium or large radius.
- Add blur only when the surface sits over a background or image.
- Use a soft warm shadow, not a floating black box.
- Add one small visual detail: icon tile, ordinal, status dot, progress bar, or AI marker.
- Give the panel one clear reading order.

For a primary action:

- Use an ink-filled pill or rounded control.
- Use white text, semibold weight, and a small directional icon when useful.
- Add a 2-4px hover lift or subtle shadow.
- Preserve a visible focus ring.
- Show disabled, loading, success, and error states when the action can take time or fail.

For a secondary action:

- Use a translucent or white surface with a thin border.
- Keep the label quieter than the primary action.
- Avoid making every link look like a button.

### 5. Add the AI identity

Use an amber/orange orb or marker as a recurring system character, not as random decoration.

A good orb has:

- Dark amber base.
- Conic or radial gradient layers.
- White specular highlight.
- Inset shadow for depth.
- Slow organic movement when motion is allowed.
- A text alternative such as OdyvaOS AI or Assistant active.

If an image or logo is available, use it only where identity matters. Do not make every card glow orange.

### 6. Encode product states

Use the same semantic patterns everywhere:

- Verified/success: pale green surface, green icon/text, check or completed state.
- Waiting/approval: pale yellow surface, amber/brown icon/text, lock or consent state.
- Running: blue, violet, or warm red signal, progress indicator, live label.
- Failure/risk: pale red surface, red icon/text, explicit recovery action.
- Empty: quiet inset surface with one next action.
- Loading: skeletons that match the final content shape; use spinners only when the shape is unknown.
- Disabled: reduced contrast and no pointer affordance, but preserve readable text.

Never communicate state with color alone. Include words, icons, shapes, position, or progress.

### 7. Make it responsive

Start from the narrowest useful layout, then expand:

- 375px: stack content, keep cards full width, shorten labels, allow intentional horizontal scrolling for dense tables.
- 768px: introduce 2-column sections and wider control groups.
- 1024px+: use split layouts, side rails, and larger visual frames.
- 1280px+: allow 12-column relationships, but keep the content measure readable.

On mobile, reduce decoration before reducing content clarity. Do not shrink type below comfortable reading sizes to preserve a desktop composition. Avoid fixed widths, viewport-breaking absolute art, and hover-only interactions.

### 8. Make interactions real

Wire the behavior that the visual implies:

- Tabs change visible content and expose the active state.
- Menus open, close on Escape, and close on outside interaction.
- Forms validate and show submission progress and completion.
- Timeline steps can be selected and reveal evidence.
- Approval actions clearly show pending, approved, rejected, and expired.
- Links go somewhere meaningful.
- Async content has loading, empty, retry, and error states.

Use the existing icon library where present. Use accessible names for icon-only controls and semantic elements before adding ARIA.

## Page recipes

### Marketing or landing

Use a calm hero with one short eyebrow, one tightly tracked outcome headline, one supporting paragraph, and two actions. Follow with proof or comparison, a rounded product showcase, a capability grid, a trust/memory section, and a dark closing CTA. Keep sections separated by whitespace and thin rules rather than boxed containers everywhere.

### Dashboard or workspace

Use a warm page background, compact top bar, clear section title, and one dominant panel. Put metrics or filters near the top, the operational list or timeline in the main column, and evidence/details in a quieter rail. Use status badges and progress bars sparingly. Favor scannability over decorative storytelling.

### Timeline or execution

Use a vertical list of steps with state markers, concise labels, duration/tool metadata, and an active progress line. Selecting a step opens evidence: output, command, permission tier, or linked artifact. Place approval in a distinct warm-yellow panel and keep the action explicit.

### Form or onboarding

Use a glass card with visible labels, 44-48px fields, calm helper text, a single high-contrast submit action, and a clear success state. Keep selection controls tactile and keyboard accessible. Use reassurance copy about privacy or next steps only when it is true.

### Table or marketplace

Use a soft inset table surface, compact uppercase column labels, generous row height, one highlighted result or status, and horizontal scrolling on small screens. Use filters as quiet controls. Keep category colors semantic and limited.

### Settings or preferences

Use a left-side section list or tabs plus one focused form surface. Group controls under short headings. Keep destructive actions visually separate and explicit. Do not turn every setting into a card; use whitespace and rules to group related controls.

## Motion system

Use motion as feedback, not spectacle:

- Fast interaction: 120ms ease-out.
- Enter: 180ms ease-out.
- Exit: 150ms ease-in.
- Consent or approval entrance: 220ms spring-like easing.
- Progress/state transition: 150-200ms.
- Orb or ambient identity loop: 6-10 seconds.
- Hover lift: 2-4px; do not scale whole cards dramatically.

Animate opacity, translate, progress, and small highlights. Avoid parallax, autoplaying hero videos, multiple simultaneous pulses, or animation that makes text hard to read.

Always implement a reduced-motion path:

    @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;
      }
    }

## Accessibility and quality gates

Before handoff:

- Test keyboard navigation, focus visibility, Escape behavior, and logical tab order.
- Give every form control a label and every icon-only control an accessible name.
- Maintain readable contrast for text, controls, placeholders, and states.
- Provide a text equivalent for charts, timelines, orb states, and live activity.
- Use polite live regions for progress and assertive announcements for approvals or errors.
- Keep touch targets at least 44px.
- Check 375px, 768px, and desktop widths for overflow and broken hierarchy.
- Verify hover, focus, active, disabled, loading, empty, error, and success states relevant to the task.
- Run the project?s typecheck, build, lint, or narrowest relevant tests.
- Remove placeholder copy, dead buttons, console errors, and accidental horizontal scrolling.

## Anti-patterns

Do not:

- Use generic purple-on-white SaaS styling as the default.
- Mix unrelated design languages across sections.
- Make every surface opaque, bordered, and shadowed.
- Use gradients as decoration without hierarchy or meaning.
- Use orange, green, yellow, red, blue, or violet merely to make a page colorful.
- Hide important state in hover, animation, or an icon with no label.
- Build a static screenshot when the task asks for an interaction.
- Overuse rounded cards until the page has no visual structure.
- Use huge headings with no supporting content or action.
- Copy a source page's exact layout when the new product job needs a different composition.

## Optional calibration

When this repository or another reference exists, use it to confirm naming, asset paths, component APIs, and exact implementation details after applying the system above. The skill must still produce a complete design when no reference files, screenshots, or existing components are available. The bundled reference guide is supplementary, not a prerequisite.