AkurAI-Build

public
Latest change 0cf28150faedd8c150474a4f16be4c9922c04f56 - feat: add Ponytail UI design system by Olafur Bui
# Ponytail UI foundation research

Research date: 2026-07-11

## Decision

Bunfork now has a clean-room, CSS-first UI layer built for MiniJinja and semantic HTML. It takes ideas from established systems but copies no component source, assets, names, or visual trade dress.

Ponytail is an agent skill and implementation discipline, not a CSS framework. The pinned Ponytail reference recommends native controls, CSS custom properties, `prefers-color-scheme`, responsive Grid, `<details>`, `<dialog>`, `<progress>`, and the browser APIs before dependencies. See its [platform-native guide at commit `14a0d795`](https://github.com/DietrichGebert/ponytail/blob/14a0d79548d4de8fc2de95c1b94bb0de63a739d3/docs/platform-native.md#L1-L50).

Tailwind CSS 4 is an influence only at the theme-contract level: CSS-first variables, token namespaces, and selector-driven dark mode. Ponytail UI is not a Tailwind fork, utility-compatible implementation, source port, or build-time compiler.

## Why a local CSS layer

- Bunfork native pages already ship one validated, preloaded public asset tree.
- MiniJinja emits ordinary HTML and needs no React or Web Component runtime.
- The browser already supplies the strongest baseline for forms, disclosure, progress, date input, color schemes, and top-layer popovers.
- Importing Bootstrap, Carbon, or Pico wholesale would add unused surface and imply compatibility that Bunfork does not provide.
- Styling a control does not transfer the keyboard behavior of Radix, Material, Fluent, or another runtime library.

The result is a small contract: semantic `--pt-*` tokens, `.pt-*` composition and component classes, native state attributes, and presentation-only `data-mode`, `data-palette`, `data-tone`, and `data-variant` attributes. Native semantics stay intact, but the user-agent skin is replaced across every visible control and state.

## Source matrix

The commit links below pin the repositories reviewed for this foundation.

| System | Pinned source | License/status | Idea retained |
| --- | --- | --- | --- |
| Tailwind CSS 4 | [`35a3e9c`](https://github.com/tailwindlabs/tailwindcss/tree/35a3e9c5159bea77af0d48f0c8849279211cc7e9) | MIT | CSS-first token posture and dark-mode selector model |
| Radix Themes | [`1faff10`](https://github.com/radix-ui/themes/tree/1faff10ac26ae17f09944d418c6949b93fc6b566) | MIT | Variant restraint, state vocabulary, focus anatomy |
| Radix Primitives | [`e4e0664`](https://github.com/radix-ui/primitives/tree/e4e06649716b0134ece0df9e067403992cfeb47d) | MIT | Overlay, menu, tabs, and disclosure behavior to test before claiming |
| shadcn/ui | [`3cdaa6e`](https://github.com/shadcn-ui/ui/tree/3cdaa6eb2f0da27aca8598cb752c32d840e06940) | MIT | Readable recipes and owned component code philosophy |
| Primer Primitives | [`c305c51`](https://github.com/primer/primitives/tree/c305c517b2f41f078953ef90c53cbb8d4535fda1) | MIT | Compact metadata, navigation density, semantic token roles |
| Carbon | [`bc66fc7`](https://github.com/carbon-design-system/carbon/tree/bc66fc71eae0d335f915ac6b01f013b78a6d2f89) | Apache-2.0 | Data tables, status feedback, explicit component modules |
| Material Web | [`b4af72e`](https://github.com/material-components/material-web/tree/b4af72e91e510fd495f15b6accb14117a9d0b27d) | Apache-2.0 | Control anatomy, state layers, progress and selection semantics |
| Bootstrap | [`b37afd7`](https://github.com/twbs/bootstrap/tree/b37afd77f69b97ae67722a9c3edb5ec5339544f3) | MIT | Broad native-control coverage and responsive conventions |
| GOV.UK Frontend | [`d5bc6f6`](https://github.com/alphagov/govuk-frontend/tree/d5bc6f61a5245dfced6a114278fcbb253ed9bc77) | MIT | Error summaries, labelled fields, skip links, server-rendered clarity |
| USWDS | [`6363387`](https://github.com/uswds/uswds/tree/636338773b3c296e9b9454f3840e5a7791bcf56d) | Mixed public-domain and third-party terms | Government-service navigation, step flows, validation |
| Fluent UI | [`bc5035b`](https://github.com/microsoft/fluentui/tree/bc5035bfcd53277a39075c596b14b9731020d1de) | MIT at repository level; verify package | Forced-colors thinking, control states, scheduling concepts |
| Shopify Polaris | [`2b1ea88`](https://github.com/Shopify/polaris/tree/2b1ea88625e0613853ca8577c9acd1980a90f382) | Verify the exact package and file | Commerce language, resource selection, bulk actions |
| Pico CSS | [`1039a47`](https://github.com/picocss/pico/tree/1039a4788d6abc368d5485ae6bac84a8f0e3096f) | MIT | Closest architecture: style semantic HTML with few classes |
| Ponytail | [`14a0d79`](https://github.com/DietrichGebert/ponytail/tree/14a0d79548d4de8fc2de95c1b94bb0de63a739d3) | MIT | Native platform first, dependencies only when behavior earns them |

Atlassian's design site was reviewed for conceptual taxonomy only. Its license is not treated as an open-source component grant, so no Atlassian code, tokens, assets, or copy were adapted.

## Twenty component genres

The live route at `/examples/components` implements one specimen for each genre below.

| Genre | Main references | Bunfork implementation boundary |
| ---: | --- | --- |
| 1. Actions and toolbars | Radix Themes, shadcn/ui | Real buttons and links; primary, secondary, quiet, danger, disabled |
| 2. Text fields | GOV.UK, USWDS | Visible label, hint, stable IDs, adjacent error text |
| 3. Choice controls | Material Web, Bootstrap | Fully themed radio, checkbox, switch, select, range, file, and color controls with native state |
| 4. Validation summary | GOV.UK | Summary links to fields; field errors remain authoritative |
| 5. Search and command input | Primer, shadcn/ui | URL-backed themed search; suggestions deferred until a custom combobox is fully themed and keyboard-tested |
| 6. Primary navigation | Primer, Fluent UI | Labelled nav, real URLs, visible current page |
| 7. Breadcrumbs and pagination | USWDS, Primer | Ordered location and labelled page sequence |
| 8. Linked tabs | Radix, Material | Real destinations; in-page roving focus deferred |
| 9. Disclosure and accordion | GOV.UK, HTML standard | Native details and summary |
| 10. Popover and action menu | Radix, HTML standard | Native Popover API for a simple action list |
| 11. Alerts and banners | Carbon, USWDS | Static status with heading and text; no live-role misuse |
| 12. Toast, progress, and loading | Carbon, Fluent UI | Static specimen, native progress, reduced-motion skeleton |
| 13. Cards and empty states | Pico, Primer | One bounded object or one recovery-oriented empty state |
| 14. Lists and tables | Carbon, Primer | Caption, scoped headers, tabular figures, narrow-screen scroll |
| 15. Badges, avatars, and status | Primer, Carbon | Textual status and correctly decorative avatars |
| 16. Commerce and pricing | Polaris | Product, data price, quantity, and sample-data disclosure |
| 17. Authentication and profile | Material, Fluent UI | Input types, autocomplete, visible labels, recovery link |
| 18. Calendar and scheduling | Fluent UI, Material | Native date input plus semantic time elements |
| 19. Messaging and activity | Primer; Atlassian concepts only | Readable list with actor, verb, and timestamp |
| 20. Metrics, steps, and bulk actions | Carbon, USWDS, Polaris | Definition-list metrics, ordered steps, checkbox form |

## Behaviors deliberately deferred

These patterns are not complete merely because CSS can imitate them:

- ARIA menu with roving focus and typeahead
- In-page tabs with Arrow, Home, and End key behavior
- Combobox with active-descendant management
- Modal dialog focus trapping, cancellation, and focus return
- Dynamic toast queue and live-region announcements
- Async form loading, retry, and optimistic state
- Persistent user-selected theme

When a real Bunfork application requires one, implement one small enhancement against a no-script server fallback and test it with keyboard and assistive technology. Do not port an upstream runtime abstraction wholesale.

## License and provenance rules

1. Inspiration means reimplementing the observable semantic pattern with Bunfork names and values.
2. Literal adaptation requires the exact upstream file, immutable commit, copyright notice, and license review.
3. Apache-2.0 source requires notice and license obligations if code is adapted.
4. USWDS, Fluent, and Polaris require file or package review before any source or asset reuse.
5. Atlassian remains concept-only.
6. Fonts, icons, logos, and brand assets can have terms separate from source code. Ponytail UI includes none of them.
7. `THIRD_PARTY_NOTICES.md` changes only if source or assets are actually incorporated. Current Ponytail UI is clean-room work, so no notice change is needed.

## Primary standards

- [HTML interactive elements](https://html.spec.whatwg.org/multipage/interactive-elements.html)
- [HTML Popover API](https://html.spec.whatwg.org/multipage/popover.html)
- [CSS Color Adjustment and `color-scheme`](https://drafts.csswg.org/css-color-adjust/)
- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/)