AkurAI-Build

public

Latest change 0cf28150faedd8c150474a4f16be4c9922c04f56 - feat: add Ponytail UI design system by Olafur Bui

---
name: Bunfork Ponytail UI
description: A small, candid interface system for Bunfork native pages.
colors:
fork-accent-light: "#176c3a"
fork-accent-dark: "#82efad"
on-accent-light: "#ffffff"
on-accent-dark: "#07120b"
canvas-light: "#f6faf7"
canvas-dark: "#090c0a"
surface-light: "#ffffff"
surface-dark: "#111713"
ink-light: "#142119"
ink-dark: "#f4f7f4"
muted-light: "#3f5446"
muted-dark: "#b1bcb4"
border-light: "#c9d8cd"
border-dark: "#303c33"
warning-light: "#8a4a12"
warning-dark: "#f1aa6d"
danger-light: "#a9362a"
danger-dark: "#ff9d86"
typography:
display:
fontFamily: "ui-sans-serif, system-ui, sans-serif"
fontSize: "clamp(2.75rem, 7vw, 5.5rem)"
fontWeight: 760
lineHeight: 1.02
letterSpacing: "-0.04em"
headline:
fontFamily: "ui-sans-serif, system-ui, sans-serif"
fontSize: "clamp(1.8rem, 3.5vw, 2.6rem)"
fontWeight: 760
lineHeight: 1.08
letterSpacing: "-0.03em"
body:
fontFamily: "ui-sans-serif, system-ui, sans-serif"
fontSize: "1rem"
fontWeight: 400
lineHeight: 1.65
label:
fontFamily: "ui-sans-serif, system-ui, sans-serif"
fontSize: "0.875rem"
fontWeight: 720
lineHeight: 1.35
rounded:
xs: "3px"
sm: "6px"
md: "8px"
lg: "12px"
pill: "999px"
spacing:
xs: "4px"
sm: "8px"
md: "16px"
lg: "24px"
xl: "32px"
section: "64px"
components:
button-primary:
backgroundColor: "{colors.fork-accent-light}"
textColor: "{colors.on-accent-light}"
rounded: "{rounded.md}"
padding: "11px 16px"
height: "44px"
button-secondary:
backgroundColor: "{colors.surface-light}"
textColor: "{colors.ink-light}"
rounded: "{rounded.md}"
padding: "11px 16px"
height: "44px"
input-default:
backgroundColor: "{colors.surface-light}"
textColor: "{colors.ink-light}"
rounded: "{rounded.md}"
padding: "11px 13px"
height: "44px"
panel-default:
backgroundColor: "{colors.surface-light}"
textColor: "{colors.ink-light}"
rounded: "{rounded.lg}"
padding: "24px"
---

# Design System: Bunfork Ponytail UI

## Overview

**Creative North Star: "The Open Workbench"**

Bunfork should feel like a clear work surface with real tools already laid out. The visual voice is mechanical, grounded, and candid. Controls look operable, boundaries are honest, and the forkbird green signals action without turning every surface into branding.

The system uses native HTML before custom behavior, CSS custom properties before hard-coded component values, and tonal layering before shadows. Native controls keep their browser semantics but never their unstyled user-agent appearance. It rejects generic AI-tool indigo, decorative glass, terminal cosplay, endless card grids, and a framework dependency for work the browser already performs.

**Key Characteristics:**

- CSS-first and server-rendered
- Light and dark hierarchy with the same semantic roles
- Restrained green identity with optional scoped palettes
- Comfortable documentation density
- Native semantics with a complete token-driven visual skin
- Explicit state and visible focus
- No client build step and no implied Tailwind compatibility

## Colors

The default Fork palette pairs green action with green-tinted neutrals. Tide, Ember, and Berry may replace the accent roles for a complete page, but they never mix casually within one composition.

### Primary

- **Fork Signal:** The primary action, current state, selection, focus, and verified status color. Light and dark values are separate so the brand remains recognizable and contrast remains stable.
- **On Signal:** Text and glyph color used only on a solid accent surface.

### Secondary

- **Tide:** A blue accent for information-heavy embedded products.
- **Ember:** A warm accent for direct action or physical-product examples.
- **Berry:** An expressive accent for campaign or community surfaces.

### Neutral

- **Canvas:** The page background. It is never pure white or pure black.
- **Surface:** The contained-content background used by panels, controls, and top-layer content.
- **Ink:** Primary text and high-importance control labels.
- **Muted Ink:** Supporting prose that still reaches normal-text contrast.
- **Border:** Quiet grouping. Use the stronger structural border when the edge identifies a control.

**The One Palette Rule.** Pick one accent palette per page. Nested palette scopes are for documentation previews and embedded products, not decoration.

**The Meaning Needs Words Rule.** Success, warning, danger, and information always include a plain-language label. Color is never the only signal.

## Typography

**Display Font:** System UI sans with platform fallbacks
**Body Font:** System UI sans with platform fallbacks
**Label/Mono Font:** Cascadia Code or the platform monospace stack for code and changing numbers only

**Character:** One familiar sans family keeps the product fast and direct. Hierarchy comes from size, weight, measure, and spacing rather than a decorative font pairing.

### Hierarchy

- **Display** (760, fluid 44-88px, 1.02): landing-page statements with a maximum of two lines and no tighter than -0.04em tracking.
- **Headline** (760, fluid 29-42px, 1.08): page and major section titles.
- **Title** (720-760, 18-26px, 1.2): components and bounded content groups.
- **Body** (400, 16px, 1.65): prose capped near 70 characters per line.
- **Label** (720, 14px, sentence case): field labels, navigation, and compact metadata.

**The Mono Earns It Rule.** Use monospace for code, commands, keyboard keys, protocol values, and tabular figures. Technical subject matter alone is not a reason.

**The Readable First Rule.** Body text never drops below 16px on mobile. Headings balance; prose wraps prettily and allows long identifiers to break.

## Elevation

Ponytail UI is flat by default. Canvas, surface tone, border strength, and spacing communicate most hierarchy. The only routine shadows are a small one-pixel depth cue for selected segmented controls and an eight-pixel popover shadow for top-layer separation.

### Shadow Vocabulary

- **Control lift** (`0 1px 2px rgb(0 0 0 / 12%)`): selected items inside a bounded segmented control.
- **Top layer** (`0 4px 8px rgb(0 0 0 / 16%)`): popovers, dialogs, and transient messages only.

**The Edge or Shadow Rule.** A component may use a structural border or visible elevation. Do not combine a hairline border with a wide soft shadow as decoration.

**The Top Layer Earns Depth Rule.** Static content remains flat. Shadows appear only where content actually rises above the document.

## Components

Components are ordinary HTML with one namespaced class family. Native attributes express native state. Presentation-only variants use a small data-attribute vocabulary.

The runtime API is always `.pt-*`. The ten `.ds-*` records in `.impeccable/design.json` are self-contained shadow-DOM previews required by the Impeccable design panel; they are not production classes and do not represent the 20-genre catalog inventory.

### Buttons

- **Shape:** Gently squared corners at 8px, minimum 44px height, and content-sized width.
- **Primary:** Solid accent with the matching on-accent color.
- **Hover / Focus:** Darker or lighter accent shift, one-pixel active press, and a three-pixel visible focus outline.
- **Secondary / Quiet / Danger:** Surface with structural border, transparent text action, and semantic destructive action respectively.

### Chips

- **Style:** Full pill only because the object is compact metadata. The default uses a surface tint and quiet structural border.
- **State:** Status text accompanies semantic color. Interactive tags must be links or buttons, not styled spans.

### Cards / Containers

- **Corner Style:** 12px maximum for cards and panels.
- **Background:** Surface tone selected from the active mode.
- **Shadow Strategy:** None at rest.
- **Border:** One quiet full border when the object needs a bounded edge.
- **Internal Padding:** 16-24px for components; larger page sections use spacing rather than a larger card.

### Inputs / Fields

- **Style:** Visible label above the control, 8px radius, surface fill, structural border, and 44px minimum height.
- **Coverage:** Text, search, number, date, time, file, color, select, textarea, checkbox, radio, switch, range, progress, and meter all use the active theme. Default user-agent visuals are removed or contained inside a themed control.
- **Native Affordances:** Search cancel and numeric stepper chrome is visually suppressed while native Escape and arrow-key behavior remains.
- **Focus:** Three-pixel accent outline with separation from the component edge.
- **Error / Disabled:** Error border plus adjacent recovery text; native disabled semantics plus reduced emphasis.

### Navigation

Navigation uses labelled landmarks, ordinary links, a minimum 44px target, and `aria-current="page"`. Tabs remain URL-backed links until full keyboard behavior is implemented. Breadcrumbs use ordered lists; pagination labels its region and current page. Pages can override the base layout's `document_language` and `document_direction` blocks; shared inline positioning uses logical properties so `rtl` mirrors without a second stylesheet.

### Native Disclosure

`details` and `summary` are the default accordion. The Popover API is the default simple top-layer action list. Critical flows stay on dedicated pages unless dialog focus, cancellation, and return behavior are implemented and tested.

**The Native State Rule.** Use `disabled`, `checked`, `open`, `required`, `aria-current`, and `aria-invalid` before inventing a state class.

**The No User-Agent Skin Rule.** Preserve native semantics and platform behavior, but replace every visible default browser treatment with semantic Ponytail UI tokens.

**The Behavior Must Be Real Rule.** CSS that resembles a menu, tab, combobox, dialog, or toast does not inherit the upstream library's keyboard behavior. Use a simpler native pattern until the behavior exists.

## Do's and Don'ts

### Do:

- **Do** consume semantic `--pt-*` tokens in every new component.
- **Do** keep normal text at 4.5:1 contrast or better in every palette and mode.
- **Do** use native controls and landmarks before adding script or an abstraction.
- **Do** apply the complete Ponytail UI skin to every visible control and every state.
- **Do** use documented `data-gap` and `data-width` variants under Bunfork's native-page CSP.
- **Do** keep primary actions singular and make secondary actions visibly quieter.
- **Do** use spacing and headings before reaching for a card.
- **Do** test 375px, 768px, 1024px, 1440px, 200% zoom, keyboard-only input, forced colors, and reduced motion.
- **Do** label sample data and invented prices as examples.

### Don't:

- **Don't** call Ponytail UI a Tailwind fork or compatibility layer.
- **Don't** use generic indigo gradients, glass panels, neon glow, gradient text, or decorative grid backgrounds.
- **Don't** add a tiny uppercase tracked eyebrow above every section.
- **Don't** use a side-stripe accent, a 32px card radius, or nested cards.
- **Don't** repeat equal icon-heading-text cards when a list, split, table, or disclosure is clearer.
- **Don't** expose default browser checkboxes, radio buttons, select arrows, range thumbs, file buttons, progress bars, disclosure markers, dialog chrome, or scrollbars.
- **Don't** use inline style attributes; the native CSP rejects them.
- **Don't** use color alone for status, hide focus, shrink controls below 44px, or rely on hover.
- **Don't** add JavaScript for behavior supplied by `details`, `popover`, native inputs, CSS Grid, `light-dark()`, or media queries.
- **Don't** copy upstream component code or brand assets without an exact file, pinned commit, and license review.