Guidelines

Practical rules that keep the ONCE interface consistent. These apply to both human developers and AI agents writing code in the codebase.

Animation

Motion is kept minimal and purposeful, only on hover and focus.

Allowed Transitions

What to avoid

• No entrance animations (fade-in, slide-up) on page load
• No looping animations except approved status motion (Early Access badge pulse and AI thinking loader)
• No parallax scrolling or scroll-triggered effects
• No motion that could trigger vestibular discomfort

Hover Lift

Cards use a subtle upward shift on hover:

.card:hover {
  transform: translateY(-1px);
  box-shadow: 0 4px 12px rgba(58, 69, 92, 0.08);
}

The lift is 1px: not 2px or 4px. Keep it barely perceptible.

Dark Mode

ONCE is a dark-first design system. All components are designed for dark backgrounds first, then adapted for light mode.

Implementation

• The docs site uses html.dark class toggling (Nextra’s built-in dark mode)
• The dev-app uses Tailwind’s dark: variant
• CSS custom properties swap between light and dark palettes via html.dark { ... }

Rules

• Always test new components in dark mode first
• Use var(—text-strong) and var(—text-subtle) instead of hardcoded colors
• Backgrounds should use surface tokens, not raw hex values
• Avoid pure white (#fff) on dark backgrounds, use —once-white with opacity

Naming Conventions

CSS Variables

• Brand colors: --once-{name} (e.g., --once-blue, --once-bg)
• Utility colors: --mr-{name} (e.g., --mr-approval)
• Surface tokens: --surface, --surface-muted, --surface-strong
• Text tokens: --text-strong, --text-subtle
• Font tokens: --font-sans, --font-display, --font-mono

Tailwind Classes (dev-app)

• Color utilities match the variable name: once-blue, mr-warning
• Use with standard prefixes: bg-once-blue, text-once-white, border-once-blue/20

CSS Classes (docs)

• Component classes are lowercase, hyphen-separated: card-grid, info-box, api-endpoint
• State classes use semantic names: early-access-badge, patron-badge
• Design system preview classes use ds- prefix: ds-swatch, ds-btn

Accessibility

Contrast

• Primary text on --once-bg must meet WCAG AA (4.5:1 ratio minimum)
• --once-blue-light (#6B7A99) is used instead of --once-blue for text on dark backgrounds, because the base blue does not pass contrast checks alone
• Utility colors were chosen to pass AA on both light and dark backgrounds

Focus States

• Interactive elements must have visible focus indicators
• Use outline or box-shadow for focus rings, not border, which shifts layout
• Default browser focus styles are acceptable if they remain visible on --once-bg

Reduced Motion

Respect prefers-reduced-motion for the badge pulse animation:

@media (prefers-reduced-motion: reduce) {
  .early-access-badge {
    animation: none;
  }
  .early-access-badge::before {
    animation: none;
  }
}

For AI Agents

If you are an AI agent working in this codebase:

• Always use CSS variables (var(—once-blue)), never hardcode hex values
• Use the opacity scale for text hierarchy, do not invent new colors
• Keep font-family to Manrope and JuliaMono, no other typefaces
• Cards get border-radius: 12px, code blocks get 8px, inline code gets 4px
• Test your output in dark mode. If it looks wrong in dark, it’s wrong
• When in doubt, follow existing patterns in globals.css