@aginies/ui 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# @aginies/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The components of the Aginies Design System for React: buttons, forms, tables, navigation,
+feedback, chat, agent runs and dashboard widgets, styled by `agn-` classes over the
+[`@aginies/tokens`](../tokens) custom properties. No Tailwind, no CSS-in-JS, no component
+library underneath.
+
+## Install
+
+```sh
+npm install @aginies/ui @aginies/tokens
+# optional, recommended: icons from the package instead of a CDN (see "Icons")
+npm install lucide-react
+```
+
+Peer dependencies: `react` and `react-dom` 18 or later; `lucide-react` 0.400 or later is optional.
+
+## Styles
+
+Import the two stylesheets once, at the app root, **in this order**:
+
+```js
+import '@aginies/tokens/tokens.css' // the custom properties: colour, type, space, density
+import '@aginies/ui/styles.css' // the agn- component classes that read them
+```
+
+`@aginies/ui/styles.css` does not carry the tokens, so they exist once on the page and a
+product that already loads `@aginies/tokens` keeps a single copy.
+
+**Fonts are the host's job.** The tokens name the three families; load them yourself, for
+example with the variable fontsource packages:
+
+```sh
+npm install @fontsource-variable/bricolage-grotesque @fontsource-variable/instrument-sans @fontsource-variable/jetbrains-mono
+```
+
+```js
+import '@fontsource-variable/bricolage-grotesque' // display: headings, stat values
+import '@fontsource-variable/instrument-sans' // body: everything read or operated
+import '@fontsource-variable/jetbrains-mono' // mono: eyebrows, tags, IDs, code
+```
+
+## Theme and density
+
+Light is the default. Set the theme and density with attributes, on the root or on any
+subtree:
+
+```html
+<html data-theme="dark">           <!-- light | dark; unset follows prefers-color-scheme -->
+<section data-density="comfortable"> <!-- compact (default, 32px controls) | comfortable (40/44px) -->
+```
+
+`ThemeToggle` and `useTheme` switch `data-theme` for you; `Room` inverts the theme inside
+itself, the way aginies.com does by section.
+
+**White label.** Tenant branding overrides the signal tokens on the root and nothing else:
+
+```css
+:root {
+  --signal: #0b4f5c;
+  --signal-2: #083e48; /* hover/pressed */
+  --signal-ink: #ffffff; /* text on a signal fill */
+  --signal-soft: rgb(11 79 92 / 0.12); /* focus halo, selected wash */
+}
+```
+
+Keep `--signal-ink` at 4.5:1 on `--signal`; every component reads these four, so a tenant
+colour reaches the primary button, focus, checked controls and the active canvas edge at once.
+
+## Components
+
+```jsx
+import { Button, PageHeader, Tag } from '@aginies/ui'
+
+<PageHeader eyebrow='Build' title='Agents' actions={<Button variant='primary' icon='plus'>New agent</Button>} />
+<Tag tone='ok' dot>Ready</Tag>
+```
+
+Every export is typed (`dist/index.d.ts`); the prop interfaces carry the usage notes.
+
+- **Core** — Icon, ProductIcon, AginiesMark + AginiesLogo, Eyebrow, Kbd, Text
+- **Actions** — Button, ButtonIcon, ButtonGroup, ButtonStateful, Menu, Pill, Chip + ChipGroup, CommandPalette, ThemeToggle (+ useTheme)
+- **Forms** — FormElement, Input, Textarea, Select, Checkbox, Switch, CheckboxButton, RadioGroup, Combobox, SegmentedControl, SecretField, TagInput
+- **Pickers** — Datepicker + Calendar, Timepicker + DatetimePicker, Slider, ColorPicker, Counter, DuelingPicklist, FileSelector, RichTextEditor, VisualPicker, Expression, DockedFormFooter
+- **Data** — DataTable, TreeGrid, Tree, Tile, SummaryDetail, Avatar, Badge, Tag, BlockIcon, FileCard, Feed, ActivityTimeline, Illustration, Stat, MiniChart + Sparkline, Kanban, CalendarView, Gantt, DescriptionList, Amount, CodeBlock, JsonTree, DiffView, Heatmap
+- **Layout** — Card, Toolbar, PageLayout, Room
+- **Navigation** — GlobalHeader, VerticalNavigation, Tabs, Breadcrumbs, Path, ProgressIndicator, SplitView, AppLauncher, PageHeader, BuilderHeader, BrandBand, Accordion, Carousel, SetupAssistant, WelcomeMat, MobileTabBar, Pagination, Stepper
+- **Feedback** — AginiesLoader, Skeleton + PageSkeleton, Alert, Toast, ScopedNotification, Notification, Modal + Prompt, Popover, Tooltip, Spinner, ProgressBar, ProgressRing, SidePanel, DockedComposer, DockedUtilityBar, Publisher, EmptyState
+- **Chat** — ChatThread, ChatMessage, ChatEvent, ChatSuggestions, ChatComposer, ToolCallCard, StreamingIndicator, TranscriptPanel
+- **Agent** (`widgets`) — ApprovalCard, RunTimeline, TraceSpans, RunStatus, AgentRunCard, CostBars, CanvasBlock + CanvasEdge + CanvasNote, QueueCard, CallCard
+- **Widgets** (`dashboard`) — ready-made combinations for dashboards and desks: KpiWidget, ChartCard, TaskListWidget, AiInsightWidget, FilterBar, RecordSummaryWidget, TeamWorkloadWidget, ActivityWidget, QuickActions, NotificationsWidget, AgentFlowWidget, LeaderboardWidget, AgendaWidget, OnboardingWidget, CommentsWidget
+
+The bundle starts with `'use client'`, so it works from the Next.js App Router.
+
+## Rules that matter to a consumer
+
+- **One primary per view.** `variant='primary'` is the signal colour; everything else is
+  neutral, and ghost inside toolbars and cards.
+- **Sentence case** for every visible string, buttons included ("Save changes", "Yeni ajan").
+  Column headers and eyebrows are uppercase by style; type them in sentence case.
+- **Status is never colour alone.** A tone comes with a word or a glyph: `circle-check` ok,
+  `triangle-alert` warn, `circle-alert` bad, `info`, `loader-circle` running, `hand` human
+  approval, `sparkles` AI-generated.
+- **`lang="tr"` on Turkish text that is uppercased by style** (eyebrows, column headers, tags),
+  or on an ancestor, so `i` becomes `İ` and not `I`.
+- Icon-only buttons (`ButtonIcon`) always take `label`: it is the accessible name.
+
+## Icons
+
+`Icon name='circle-check'` renders a Lucide glyph as inline SVG (stroke 2 at 16px and below,
+1.75 above). Where the glyphs come from:
+
+1. **`lucide-react`, when installed** — imported once with a dynamic `import('lucide-react')`
+   and cached. Supported from 0.400 through the 1.x line.
+2. **Otherwise the Lucide UMD bundle** (`lucide@0.468.0`) loaded once from unpkg, as in the
+   design system's own previews.
+
+Props and markup are the same either way. Glyphs appear after mount (server rendering emits
+the empty `svg`, sized, so layout does not shift). Install `lucide-react` in production: it
+removes the third-party script and works under a strict Content-Security-Policy. Because the
+import is a literal `import('lucide-react')`, a bundler that treats an unresolvable import as
+an error will want the package installed (or marked external) even when you rely on the
+fallback.
+
+`ProductIcon` (the seven product glyphs), `AginiesMark` and `AginiesLogo` are inline SVG and
+need neither.
+
+## Developing this package
+
+`src/` is generated. The Aginies Design System is the source of truth; this package mirrors
+it with one command:
+
+```sh
+DS_DIR=/path/to/design-system bun run --filter @aginies/ui sync
+```
+
+`scripts/sync-from-ds.ts` copies the component sources, concatenates the export fragments
+into `src/index.js`, the stylesheets into `src/styles.css` and the group declarations into
+`src/index.d.ts`, applies the one package-specific patch (the `lucide-react` icon source
+above; it fails loudly if the design system's `Icon.jsx` no longer has the code it patches)
+and removes files that are gone upstream. Fix components in the design system and re-sync;
+an edit under `src/` is overwritten by the next sync, which is also why Biome skips
+`packages/ui/src`.
+
+```sh
+bun run --filter @aginies/ui build             # dist/index.js, index.cjs, index.d.ts, styles.css
+bun run --filter @aginies/ui test              # server render + every export declared
+bun run --filter @aginies/ui type-check        # the declarations as a consumer sees them
+bun run --filter @aginies/ui type-check:strict # also lib-checks src/index.d.ts itself
+```