@logicplanes/kaeso-ui 0.1.0

package/foundations/elevation.md

@@ -0,0 +1,23 @@
+# Elevation
+
+Few levels, each with one job. Lines are rings drawn with shadows; depth comes from tone first and shadow second. Values: `../ai/tokens.md`.
+
+## Levels
+
+| Utility          | Use                                                                                   |
+| ---------------- | ------------------------------------------------------------------------------------- |
+| `shadow-ring`    | A hairline inside the edge: badges, tags, key caps, provider tiles.                   |
+| `shadow-frame`   | A hairline outside the edge, for content that reaches it: previews, embedded screens. |
+| `shadow-control` | Secondary buttons, inputs, selects: a ring and a shadow you feel more than see.       |
+| `shadow-segment` | The raised item inside a segmented track.                                             |
+| `shadow-panel`   | The content panel on the chrome.                                                      |
+| `shadow-raised`  | Menus, popovers, tooltips.                                                            |
+| `shadow-dialog`  | Dialogs, sheets, the command palette.                                                 |
+| `shadow-toast`   | The toast capsule.                                                                    |
+
+## Rules
+
+- Never a CSS border on a control: rings are box-shadows, so they never change the box size.
+- A hairline is the same on all four sides. Controls and small marks draw it inside their own edge, so a scroller or a truncating table cell never cuts a side off; cards, tables and overlays, whose content reaches their edge, draw it outside, opaque and above their shadow. No top light: a highlight along one edge reads as that side drawn thicker.
+- In light mode, shadows carry the lift. In dark mode they disappear into black, so a lighter ring does it instead.
+- One overlay level at a time. A menu inside a dialog uses the raised level, not a deeper one.

package/foundations/icons.md

@@ -0,0 +1,14 @@
+# Icons
+
+Hugeicons, Stroke Rounded, one icon per Kaeso concept. The same idea always looks the same. Every name: `../ai/icons.md`.
+
+## Vocabulary
+
+Use the names, not the icons: `icons.key` always means a key, `icons.model` a model. Import `icons` from `@logicplanes/kaeso-ui` and pass one to a component's `icon`, `leadingIcon` or `trailingIcon`, or to `<Icon icon={icons.key} size="md" />`. Sizes: `xs`, `sm`, `md`, `lg`, `xl`.
+
+## Rules
+
+- An icon accompanies a word or names a button that has an accessible label. Decorative icons are hidden from assistive technology.
+- No decorative icons: empty states, dialogs and badges carry words, not symbols.
+- Icons sit quieter than their label (text secondary) and take the label's color when active.
+- Stroke icons next to text are centered on the cap height, not the box.

package/foundations/motion.md

@@ -0,0 +1,39 @@
+# Motion
+
+Quick, decelerating, from the trigger, never bouncing and never in the way. Motion explains where something came from; it never decorates. Durations and curves: `../ai/tokens.md`.
+
+## Durations
+
+| Token                                                | Use                                          |
+| ---------------------------------------------------- | -------------------------------------------- |
+| `--k-duration-fast`                                  | Hover, press and color changes               |
+| `--k-duration-overlay`, `--k-duration-close-overlay` | Menus and popovers opening, closing          |
+| `--k-duration-dialog`, `--k-duration-close-dialog`   | Dialogs opening, closing                     |
+| `--k-duration-sheet`, `--k-duration-close-sheet`     | Sheets opening, closing                      |
+| `--k-duration-toast-in`, `--k-duration-toast-out`    | A toast arriving, leaving                    |
+| `--k-duration-indicator`                             | Tab and segment indicators, the switch thumb |
+| `--k-duration-disclosure`                            | Collapsibles and sidebar groups              |
+| `--k-duration-chart`                                 | Chart values changing                        |
+| `--k-duration-check`, `--k-duration-radio`           | The checkmark drawing in, the radio dot      |
+| `--k-duration-copied`                                | How long "Copied" stays                      |
+
+## Easing
+
+Things that arrive decelerate (`standard`, `overlay`); things that leave accelerate (`exit`) and take less time. `pulse` is for loading only.
+
+## Loading
+
+Loading keeps one beat of 800ms on the pulse easing. The spinner is three routes on a ring, like the three branches of the mark; it advances a third of a turn per beat. The skeleton breathes over two beats.
+
+- A busy control says so at once (`aria-busy`, clicks ignored); its spinner waits out the 300ms delay, then stays at least 400ms so it never flickers. `useDelayedLoading` times any other indicator the same way.
+- A page's own indicator that goes away with the page can wait out the delay in CSS alone: `show-after-delay`.
+- A skeleton shows at once: it is the shape of the page, not an indicator.
+- With reduced motion the ring holds still and the light passes from route to route by opacity alone; skeletons hold still.
+
+## Rules
+
+- Overlays scale from 0.96 and fade from their trigger; dialogs from 0.98 in the center; sheets slide from their edge.
+- No page-enter animation and no loops but loading's.
+- Never `transition: all`; only the properties that change.
+- With reduced motion, transforms are removed and only opacity changes remain.
+- Input is never blocked by an animation: a closing menu does not delay the next click.

package/foundations/psychology.md

@@ -0,0 +1,36 @@
+# Psychology
+
+People spend hours a day in this interface. Every rule in the library traces back to how people perceive, decide and feel; review every screen against the rules below.
+
+## The rules
+
+1. **One of everything.** One type scale, one spacing scale, one control height per size, one pattern per job. _(Processing fluency)_
+2. **Polish is function.** Visual defects are bugs. _(Aesthetic–usability effect)_
+3. **Space signals quality.** Generous margins and 48px section gaps; never cram. _(White space and prestige)_
+4. **Round what people touch.** Pills for single-line controls, concentric radii for containers. _(Curved-shape preference)_
+5. **Space before lines before boxes.** Group by proximity and tone; frame only the surfaces in `elevation.md`. _(Gestalt)_
+6. **Big, close targets.** 32px minimum (44 coarse), row-wide hit areas, menus beside triggers, actions at row ends. _(Fitts)_
+7. **Few choices at once.** One primary action per view; ≤ 7 items per menu group; advanced options disclosed. _(Hick–Hyman, choice overload)_
+8. **Recognition over recall.** Names beside ids, providers beside models, units beside numbers. _(Cognitive load, working memory)_
+9. **Color means something.** Monochrome interface; color only for status and data. _(Pre-attentive processing)_
+10. **Steps you can see, and no bigger.** State fills ≈ 3–4 L* apart. _(Just-noticeable difference)_
+11. **Never color alone.** Every status carries a word or an icon. _(Pre-attentive processing; WCAG 1.4.1)_
+12. **Dark mode is designed, not inverted.** `#fafafa` text on black; weights 20 lighter; parity reviewed side by side. _(Halation and irradiation)_
+13. **Measured contrast.** Every pair measured; 12px minimum text; tertiary never carries meaning alone. _(Contrast sensitivity, WCAG 2.2, APCA)_
+14. **Read along an edge.** Left-aligned labels, right-aligned tabular numbers, prose ≤ 68ch. _(Reading and scanning)_
+15. **Answer within 100 ms.** CSS-only hover and press; skeletons under 1 s; progress beyond. _(Response time limits)_
+16. **Motion confirms, then stops.** 120–240 ms, decelerating, no overshoot, no page-enter, no loops. _(Motion perception)_
+17. **Controls look like controls.** Fill + ring + shadow; non-controls never mimic them. _(Affordance and signifiers)_
+18. **One ink button.** Exactly one primary per view. _(Von Restorff)_
+19. **Important at the ends.** Most-used navigation first, account and help last, primary action last in a footer. _(Serial position)_
+20. **Show progress, never nag.** No setup checklists or numbered step lists; a new project shows its normal screens with their empty states, and a task in several steps is a `StepDialog`. _(Goal-gradient, Zeigarnik)_
+21. **Care for the peaks.** The key reveal, the first request and errors get extra space and calm copy. _(Peak–end rule)_
+22. **Undo over confirm.** Reversible actions are instant and undoable; irreversible ones explain themselves. _(Self-determination, perceived control)_
+23. **Quiet is premium.** Restraint, monochrome, precise type, nothing loud; simplify what looks busy at 50%. _(Luxury cues, visual complexity)_
+
+### Learned in review
+
+24. **Nothing moves when its state changes.** A button that reads “Copy page” keeps its width when it reads “Copied”; loading, hover, selected and open keep the box. Every label variant is reserved in one grid cell. _(Found in review: a shrinking button reads as a glitch and moves the pointer's target.)_
+25. **Rings follow the keyboard.** Focus rings appear for keyboard focus only; a clicked control looks clean, never "stuck selected". _(Found in review: a ring left after a click reads as an error state.)_
+26. **Words, not symbols.** Empty states, alert dialogs, badges and status labels carry words; a decorative icon or dot beside them adds noise without meaning. _(Found in review: the icon above an empty state and the dot in a badge made screens look cheaper.)_
+27. **Every control text inherits the interface family.** No serif fallback ever renders, in portals and native controls included. _(Found in review.)_

package/foundations/shape.md

@@ -0,0 +1,41 @@
+# Shape
+
+Pills for everything on one line, concentric corners for everything that holds something. Values: `../ai/tokens.md`.
+
+## Radii
+
+| Utility                                   | Use                                                                            |
+| ----------------------------------------- | ------------------------------------------------------------------------------ |
+| `rounded-pill`                            | Every single-line control: buttons, inputs, selects, tabs, tags, sidebar items |
+| `rounded-panel`                           | The content panel of the app frame                                             |
+| `rounded-menu`                            | Menus and listbox popups                                                       |
+| `rounded-item`                            | Rows inside menus and lists (menu radius minus its 6px inset)                  |
+| `rounded-popover`                         | Popovers and hover cards                                                       |
+| `rounded-dialog`                          | Dialogs and the command palette                                                |
+| `rounded-sheet`                           | Sheets, on the side that faces the content                                     |
+| `rounded-group`                           | Settings groups                                                                |
+| `rounded-well`                            | Code wells and preview frames                                                  |
+| `rounded-tooltip`                         | Single-line tooltips                                                           |
+| `rounded-palette`, `rounded-palette-item` | The command palette and its rows                                               |
+| `rounded-checkbox`                        | Checkboxes                                                                     |
+| `rounded-org`                             | Organization avatars                                                           |
+| `rounded-kbd`                             | Key caps                                                                       |
+| `rounded-code`                            | Inline code                                                                    |
+| `rounded-bar`, `rounded-cell`             | Bars in charts, heatmap cells                                                  |
+| `rounded-avatar`                          | Small square marks                                                             |
+| `rounded-field`                           | Token fields that wrap                                                         |
+| `rounded-textarea`                        | Textareas                                                                      |
+| `rounded-cell-lg`                         | One-time code cells                                                            |
+| `rounded-tooltip-lg`                      | Tooltips that wrap                                                             |
+| `rounded-frame`                           | An app frame embedded in a page                                                |
+| `rounded-toast`                           | A toast that wraps                                                             |
+
+## Concentric corners
+
+An inner corner is the outer corner minus the inset, so curves stay parallel. A 16px menu with a 6px inset holds 10px items; a 24px frame with an 8px inset holds 16px pills.
+
+## Rules
+
+- A pill is a perfect stadium: its radius is at least half its height.
+- Nothing mixes shapes: a square button never sits next to a pill.
+- No decorative cards. Content sits on the panel; only the surfaces above it have corners of their own.

package/foundations/tokens.md

@@ -0,0 +1,24 @@
+# Tokens
+
+Every value in the library is a token. Components use role names through CSS variables and the Tailwind theme; raw values never appear in a component. Every value, light and dark: `../ai/tokens.md`.
+
+## Using tokens
+
+Import the stylesheet once. It defines the `--k-*` variables for light and dark, and a Tailwind theme in which only token values exist: `bg-panel`, `text-fg-secondary`, `h-36`, `rounded-pill`. Classes like `bg-blue-500` or `p-7` are not generated.
+
+```css
+@import "tailwindcss";
+@import "@logicplanes/kaeso-ui/tailwind.css";
+```
+
+The values are also exported as JSON (`@logicplanes/kaeso-tokens/tokens.json`) and TypeScript (`@logicplanes/kaeso-tokens`).
+
+## Lengths
+
+Every length a component may use is on a fixed list; the class suffix is the pixel value (`h-36` is 36px). A length off the list does not exist. The list is at the end of `../ai/tokens.md`.
+
+## Rules
+
+- Use the role, never the step: `text-fg-secondary`, not a gray.
+- No hex or rgb literals, no arbitrary Tailwind values or variants, no `dark:`: both themes come from the same role names.
+- Change a token, not a component, when a value is wrong everywhere.

package/foundations/typography.md

@@ -0,0 +1,35 @@
+# Typography
+
+Inter for the interface, Geist Mono for ids, keys and code. Fourteen pixels is the base; nothing readable is smaller than twelve. Sizes, line heights and tracking: `../ai/tokens.md`.
+
+## Scale
+
+Ten steps, each with its own line height and tracking. Larger sizes tighten; small sizes open up slightly.
+
+| Utility         | Use                                       |
+| --------------- | ----------------------------------------- |
+| `text-micro`    | Key caps, tiny counts                     |
+| `text-caption`  | Group labels, column headers, field hints |
+| `text-small`    | Descriptions, secondary cells, metadata   |
+| `text-body`     | The base: labels, rows, controls          |
+| `text-body-lg`  | Lead sentences, settings titles           |
+| `text-title-sm` | Section titles                            |
+| `text-title`    | Dialog and sheet titles                   |
+| `text-title-lg` | Page titles                               |
+| `text-display`  | The home page only                        |
+| `text-metric`   | Big numbers, tabular                      |
+
+## Families
+
+Inter for everything people read: "Request logs, keys and usage for every model you run." Geist Mono (`mono`) for what people copy or compare character by character: `req_01JAR2N7`, `sk-kso-AbC123…wxyz`.
+
+## Numbers
+
+Numbers that align in columns use tabular figures (`tabular`). Money keeps its exact decimal string from the API and is formatted only for display; token counts use thin grouping; durations pick their unit (`840 ms`, `2.4 s`). Use the formatters in `@logicplanes/kaeso-ui/format`.
+
+## Rules
+
+- Three weights: 400, 500 and 600. No faux bold, no light weights.
+- Dark mode renders 500 and 600 twenty units lighter, so both themes look equally heavy.
+- Sentence case everywhere, including buttons and titles.
+- Never a serif. Every control and portal inherits the interface family.

package/foundations/writing.md

@@ -0,0 +1,39 @@
+# Writing
+
+Clear enough to act on, exact enough to trust, and calm enough to stay out of the way. These are the rules that interface copy meets every day.
+
+## Rules
+
+- **Sentence case** everywhere: buttons, titles, menu items, column headers.
+- **A verb first on buttons**: "Create key", "Add model", "Disable". Never "OK" or "Submit".
+- **No exclamation points, no emoji**, no jokes, no congratulations.
+- **Errors say what did not happen and what to do next**: "Couldn't reach the provider. Check the provider key, then try again."
+- **Name the object**: "Key copied", not "Copied to clipboard".
+- **Use Kaeso's terms**: key, provider key, project, organization, model, alias, limit, budget, request log.
+- **Realistic data in examples**, never lorem ipsum.
+- **Straight apostrophes** in English: "Couldn't load these rows", "the key's name", never `’`.
+
+## Labels and placeholders
+
+A label names the field; a placeholder shows an example, never the label. Hints say what the value is used for. Required fields are the default; optional ones say "Optional".
+
+| Do                                    | Avoid                                     |
+| ------------------------------------- | ----------------------------------------- |
+| Name, with placeholder "checkout-web" | Placeholder "Enter key name" and no label |
+| "Used in request logs and alerts."    | "Please enter a valid name."              |
+
+## Empty states
+
+An empty state says what will appear and how to make it appear, in one sentence, with one action. No illustration, no icon.
+
+| Do                                                                | Avoid                  |
+| ----------------------------------------------------------------- | ---------------------- |
+| "No requests yet. Send a request with a key and it appears here." | "Nothing to see here!" |
+
+## Destructive actions
+
+Say the consequence in plain words before the action. The button repeats the verb: "Archive project", "Delete key". Reversible actions skip the confirmation and offer Undo in the toast.
+
+## Numbers and units
+
+Units sit next to numbers: `$1,284.50`, `18.4M tokens`, `840 ms`. Money keeps the decimals the API sent; an amount below the smallest place shown reads `< $0.000001`, never `$0.000000`. Counts round only for display, keep at least three significant digits (`1.23M`, `1.02亿`) and show the exact value in a tooltip.

package/package.json

@@ -0,0 +1,144 @@
+{
+  "name": "@logicplanes/kaeso-ui",
+  "version": "0.1.0",
+  "description": "Kaeso's UI library: React components on Base UI, Tailwind CSS v4 and the Kaeso tokens.",
+  "license": "MIT",
+  "author": "Devin Oldenburg",
+  "homepage": "https://ui.kaeso.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/logicplanes/kaeso.git",
+    "directory": "packages/ui"
+  },
+  "bugs": {
+    "url": "https://github.com/logicplanes/kaeso/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "kaeso",
+    "react",
+    "components",
+    "base-ui",
+    "tailwindcss",
+    "design-system"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./tailwind.css": "./dist/tailwind.css",
+    "./format": {
+      "types": "./dist/types/format/index.d.ts",
+      "import": "./dist/format.js"
+    },
+    "./theme": {
+      "types": "./dist/types/theme/index.d.ts",
+      "import": "./dist/theme.js"
+    },
+    "./utils": {
+      "types": "./dist/types/utils/index.d.ts",
+      "import": "./dist/utils.js"
+    },
+    "./i18n": {
+      "types": "./dist/types/i18n/index.d.ts",
+      "import": "./dist/i18n.js"
+    },
+    "./blocks/*": {
+      "types": "./dist/types/blocks/*/index.d.ts",
+      "import": "./dist/blocks/*.js"
+    },
+    "./ai/component-registry.json": "./ai/component-registry.json",
+    "./charts/*": {
+      "types": "./dist/types/components/charts/*.d.ts",
+      "import": "./dist/components/charts/*.js"
+    },
+    "./kaeso/*": {
+      "types": "./dist/types/components/kaeso/*.d.ts",
+      "import": "./dist/components/kaeso/*.js"
+    },
+    "./package.json": "./package.json",
+    "./*": {
+      "types": "./dist/types/components/*/index.d.ts",
+      "import": "./dist/components/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "ai",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "foundations"
+  ],
+  "peerDependencies": {
+    "@hugeicons/core-free-icons": "^4.2.0",
+    "@hugeicons/react": "^1.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@base-ui/react": "1.8.0",
+    "@tanstack/react-table": "8.21.3",
+    "@tanstack/react-virtual": "3.14.13",
+    "clsx": "2.1.1",
+    "d3-array": "3.2.4",
+    "d3-sankey": "0.12.3",
+    "d3-scale": "4.0.2",
+    "d3-shape": "3.2.0",
+    "d3-time": "3.1.0",
+    "marked": "18.0.14",
+    "react-day-picker": "9.14.0",
+    "shiki": "4.4.3",
+    "tailwind-merge": "3.7.0",
+    "uqr": "0.1.3",
+    "@logicplanes/kaeso-tokens": "0.1.0"
+  },
+  "devDependencies": {
+    "@hugeicons/core-free-icons": "4.3.5",
+    "@hugeicons/react": "1.1.10",
+    "@tailwindcss/node": "4.3.3",
+    "@tailwindcss/oxide": "4.3.3",
+    "@tailwindcss/vite": "4.3.3",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.7",
+    "@types/d3-array": "3.2.2",
+    "@types/d3-sankey": "0.12.5",
+    "@types/d3-scale": "4.0.9",
+    "@types/d3-shape": "3.1.7",
+    "@types/d3-time": "3.0.4",
+    "@types/node": "24.13.6",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitest/coverage-v8": "5.0.4",
+    "axe-core": "4.13.0",
+    "happy-dom": "21.0.1",
+    "oxlint": "1.85.0",
+    "react": "19.2.8",
+    "react-docgen-typescript": "2.4.0",
+    "react-dom": "19.2.8",
+    "tailwindcss": "4.3.3",
+    "tsx": "4.23.15",
+    "typescript": "5.9.3",
+    "vite": "8.3.4",
+    "vitest": "5.0.4"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && node scripts/build-css.mjs && node scripts/registry.mjs && node scripts/references.mjs && node scripts/budgets.mjs",
+    "lint": "oxlint --deny-warnings . && node scripts/lint.mjs",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run --coverage"
+  }
+}