@logicplanes/kaeso-ui 0.1.0

package/AGENTS.md

@@ -0,0 +1,124 @@
+# Kaeso UI for agents
+
+How an agent builds Kaeso screens with `@logicplanes/kaeso-ui`. Read this before writing interface code. It ships in the package (`node_modules/@logicplanes/kaeso-ui/AGENTS.md`) and is the page [ui.kaeso.app/for-agents](https://ui.kaeso.app/for-agents).
+
+## Load it in your project
+
+So your agent reads these rules every time it works on the interface:
+
+- **Claude Code:** add this line to your project's `CLAUDE.md`:
+
+  ```
+  @node_modules/@logicplanes/kaeso-ui/AGENTS.md
+  ```
+
+- **Codex, Cursor and other agents that read `AGENTS.md`:** add this line to your project's `AGENTS.md`:
+
+  ```
+  Before writing interface code, read node_modules/@logicplanes/kaeso-ui/AGENTS.md and follow it.
+  ```
+
+## Foundations
+
+The design system behind the components, in `node_modules/@logicplanes/kaeso-ui/foundations/`. Read the one that matches what you are doing:
+
+| File                           | Read it when                                      |
+| ------------------------------ | ------------------------------------------------- |
+| `foundations/tokens.md`        | Writing any class: only token values exist        |
+| `foundations/color.md`         | Choosing a surface, a text role or a status color |
+| `foundations/typography.md`    | Setting text, numbers, ids or code                |
+| `foundations/shape.md`         | Choosing a radius, nesting surfaces               |
+| `foundations/elevation.md`     | Drawing a line, a ring or a raised surface        |
+| `foundations/motion.md`        | Animating anything, showing loading               |
+| `foundations/icons.md`         | Placing an icon                                   |
+| `foundations/writing.md`       | Writing any label, message, empty state or error  |
+| `foundations/accessibility.md` | Building anything interactive                     |
+| `foundations/psychology.md`    | Reviewing a screen: the 27 perception rules       |
+
+## Machine-readable
+
+- `node_modules/@logicplanes/kaeso-ui/ai/component-registry.md`: every component, its import, props, types, defaults and variants, generated from the types. The same as JSON in `ai/component-registry.json`.
+- `node_modules/@logicplanes/kaeso-ui/ai/component-guides.md`: for every component, what it is for, keyboard, accessibility, do and don't, and every example's code. Read a component's section before using it for the first time.
+- `node_modules/@logicplanes/kaeso-ui/ai/tokens.md`: every token value, light and dark. `ai/icons.md`: the icon vocabulary.
+- [ui.kaeso.app/llms.txt](https://ui.kaeso.app/llms.txt): these rules and every component, in plain text.
+- [ui.kaeso.app/components.json](https://ui.kaeso.app/components.json): the registry, online.
+- Every component page on ui.kaeso.app has **Copy page**, which copies it as Markdown.
+
+## Setup
+
+With Tailwind CSS v4, in the app's stylesheet:
+
+```css
+@import "tailwindcss";
+@import "@logicplanes/kaeso-ui/tailwind.css";
+```
+
+Without Tailwind, import `@logicplanes/kaeso-ui/styles.css` once. Then wrap the app once:
+
+```tsx
+import { ThemeProvider, TooltipProvider, Toaster } from "@logicplanes/kaeso-ui";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider>
+      <TooltipProvider>
+        {children}
+        <Toaster />
+      </TooltipProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+## The rules
+
+1. **Compose, never design.** The console is built only from `@logicplanes/kaeso-ui`. If something is missing, it is added to the library, not drawn in the app.
+2. **`className` is for layout only**: margin, width, grid placement, flex. Never color, radius, shadow, font or padding on a component; use its props and variants.
+3. **Only token values exist.** `bg-panel`, `text-fg-secondary`, `h-36`, `rounded-pill`. There is no `bg-blue-500`, no `p-7`, no arbitrary values, no `dark:`.
+4. **Wrap inputs in `Field`** (or give them `label`) for the label, hint and error. A bare input without a label or an `aria-label` is a bug.
+5. **One primary button per view.** Everything else is secondary or ghost.
+6. **No decorative cards and no decorative icons.** Content sits on the panel; empty states and dialogs carry words.
+7. **Color only for data and status**, and a status always has a word.
+8. **Use the formatters** from `@logicplanes/kaeso-ui/format` for money, tokens, durations and dates. Money stays an exact decimal string.
+9. **Use the icon vocabulary**: `icons.key`, `icons.model`, never an icon picked by look.
+10. **Copy follows the voice**: sentence case, a verb first on buttons, no exclamation points or emoji, errors that say what to do next.
+11. **Leave room.** Let the panel breathe: the components bring their own spacing, so don't pack screens with extra wrappers, borders or headings. Fewer elements, each one clear.
+
+## Which component for which job
+
+| Job                                      | Use                                                             |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| App layout                               | `AppFrame` with `Sidebar`, `PageHeader`, `AppFrame.Body`        |
+| Settings page                            | `AppFrame.Settings`, `SettingsGroup`, `SettingsRow`             |
+| A collection people scan and act on      | `List` with group headers                                       |
+| A collection people compare by column    | `DataTable` (virtualized, sortable)                             |
+| Filters above a collection               | `Toolbar` with `FilterChip`, `SearchInput`, `DisplayOptions`    |
+| A choice among 2–4 views                 | `Segmented`; page sections: `PillTabs`; detail sections: `Tabs` |
+| One of many options                      | `Select`; searchable: `Combobox`                                |
+| A confirmation of an irreversible action | `AlertDialog`; deletion: the `DeleteResource` block             |
+| A task in several steps                  | `StepDialog`                                                    |
+| Feedback after an action                 | `toast()`, with Undo for reversible actions                     |
+| A secret shown once                      | `SecretReveal`                                                  |
+| Numbers at a glance                      | `MetricRow` with `Stat`; over time: `TimeseriesChart`           |
+| Nothing to show yet                      | `Empty` with one action                                         |
+
+## A screen
+
+```tsx
+import { AppFrame, Sidebar, PageHeader, Toolbar, FilterChip, SearchInput, DataTable, Button, icons } from "@logicplanes/kaeso-ui";
+
+export function RequestLogs({ rows }: { rows: LogRow[] }) {
+  return (
+    <AppFrame brandHref="/" sidebar={<ConsoleSidebar current="logs" />}>
+      <PageHeader start={<AppFrame.MenuButton />} title="Request logs" actions={<Button variant="secondary">Export CSV</Button>} />
+      <Toolbar>
+        <FilterChip property="Status" operator="is" value="2xx" />
+        <SearchInput aria-label="Search logs" placeholder="Search logs" />
+      </Toolbar>
+      <AppFrame.Body>
+        <DataTable data={rows} columns={columns} />
+      </AppFrame.Body>
+    </AppFrame>
+  );
+}
+```

package/CLAUDE.md

@@ -0,0 +1,3 @@
+The rules for building with @logicplanes/kaeso-ui are in AGENTS.md, next to this file. Inside the Kaeso repository, the root AGENTS.md governs work on the library itself; these rules are for the apps that use it.
+
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devin Oldenburg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,5 @@
+# Notices
+
+Fonts: Inter (SIL Open Font License 1.1) and Geist Mono (SIL Open Font License 1.1), self-hosted as unmodified subsets of their Fontsource builds and shipped in `dist/fonts/` with `LICENSE-Inter.txt` and `LICENSE-GeistMono.txt`. Icons: Hugeicons free, Stroke Rounded (MIT).
+
+The runtime dependencies are listed in `package.json`; each is MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0 or 0BSD licensed.

package/README.md

@@ -0,0 +1,43 @@
+# @logicplanes/kaeso-ui
+
+Kaeso's UI library: React 19 components on Base UI, styled with Tailwind CSS v4 and the Kaeso tokens. Every Kaeso interface is built from it. Its showcase at [ui.kaeso.app](https://ui.kaeso.app) shows every component live, with its props.
+
+## Install
+
+```bash
+pnpm add @logicplanes/kaeso-ui react react-dom @hugeicons/react @hugeicons/core-free-icons
+```
+
+With Tailwind CSS v4:
+
+```css
+@import "tailwindcss";
+@import "@logicplanes/kaeso-ui/tailwind.css";
+```
+
+Without Tailwind, import the prebuilt stylesheet once: `import "@logicplanes/kaeso-ui/styles.css";`
+
+```tsx
+import { ThemeProvider, TooltipProvider, Toaster, Button } from "@logicplanes/kaeso-ui";
+
+export function App() {
+  return (
+    <ThemeProvider>
+      <TooltipProvider>
+        <Button variant="primary">Create key</Button>
+        <Toaster />
+      </TooltipProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+Installation, theming and every component: [ui.kaeso.app](https://ui.kaeso.app).
+
+## For agents
+
+The package ships its rules in `AGENTS.md`. Load them in your project so every agent follows them: add `@node_modules/@logicplanes/kaeso-ui/AGENTS.md` to your `CLAUDE.md`, or tell agents in your `AGENTS.md` to read `node_modules/@logicplanes/kaeso-ui/AGENTS.md`. The registry of every component and prop is in `@logicplanes/kaeso-ui/ai/component-registry.md` (and `.json`); online as [ui.kaeso.app/components.json](https://ui.kaeso.app/components.json), and with the rules as plain text at [ui.kaeso.app/llms.txt](https://ui.kaeso.app/llms.txt).
+
+## License
+
+MIT. The Kaeso name and logo are not covered by the license. Inter and Geist Mono are bundled under the SIL Open Font License 1.1; see `NOTICE.md`.