lino-ui 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,216 @@
+# Building interface with lino-ui
+
+For agents (and people) who build screens with `lino-ui`: Svelte 5 components in lino's look, paper, ink, one
+accent, every edge cut by hand. Read this file whole before the first piece of UI; it is short, and every rule in it
+comes from review. Paths below are relative to the package (`node_modules/lino-ui/`).
+
+## At the start of every session
+
+1. Start the documentation site and tell the user where it is:
+
+   ```bash
+   npx lino docs --detach
+   ```
+
+   It prints a local URL (the same one while it runs; it starts once). Say to the user, in their language, something
+   like: "The lino-ui docs are open at http://localhost:4977: every component with live examples, its props and
+   these rules." Do it again whenever you start the app's dev server, if it is not running.
+2. Read this file. Before you use a component, read its page: `docs/<component>.md` (`docs/button.md`), or the same at
+   `<docs URL>/ds/<component>/llms.txt`. The index of every page is `docs/llms.txt`.
+
+## Setting up an app
+
+Svelte 5 with Vite (SvelteKit or plain). Once:
+
+```bash
+npm i lino-ui
+npx lino init
+```
+
+`lino init` gives the project's agents this guide: the skills (`.claude/skills`, pointers into the package, so they
+update with it), a block in `AGENTS.md` and `CLAUDE.md`, and a Claude Code hook that starts the docs with each session.
+Then, in the app's entry (SvelteKit: the root `+layout.svelte`):
+
+```js
+import "lino-ui/styles.css"; // tokens, fonts, the kit's look
+import "lino-ui/setup";      // the rough cuts, the press, the interface sounds
+```
+
+The page's background is the paper: `body { background: var(--color-background); color: var(--color-text); }`.
+
+Three themes, only the colours change: Solar (light, the default), and the dark Ink and Lunar on
+`<html data-theme="ink">` / `"lunar"`. Set the attribute before the first paint (a line of script in `<head>`), so a
+dark theme never flashes paper. Everything you build follows by itself as long as it takes its colours from tokens.
+
+## Building from a prompt
+
+1. **Read the request as surfaces, controls, content.** Surfaces are what things sit on (a panel, a menu, a dialog,
+   a card). Controls are what the user acts on. Content is text, pictures, numbers. Icons belong to controls.
+2. **Pick a component for every control and surface** (the table below). Compose; never restyle a component into
+   another one.
+3. **Lay it out on the 4px grid.** Spaces are `--space-1` 4px … `--space-8` 32px. Hug the content, the same padding
+   on every side, one height and one centre line for everything on a bar.
+4. **One surface per level.** A control on a plate uses that plate; it never brings its own fill inside it. Group by
+   space first; a separator only between real groups.
+5. **Check the list of don'ts**, then look at it in the browser (see Verify).
+
+### Which component
+
+| The user needs | Use |
+|---|---|
+| An action | `Button`: `variant="action"` on a surface, `"panel"` straight on the paper, `"accent"` for the one primary action of a view, `"ghost"` for quiet ones |
+| An action shown as an icon | `Button size="icon"` (`icon-sm`, `icon-lg`) with `aria-label`, inside a `Tooltip` with its name and shortcut |
+| Several actions joined | `ButtonGroup` |
+| On / off | `Switch` with a `Label` |
+| One of a few, all visible | `ToggleGroup` (a track); a pressed state on one button: `Toggle` |
+| A set of tools | `Toolbar` holding a `ToggleGroup variant="bare" size="icon"` |
+| One of many, or actions behind a button | `DropdownMenu` (radio items for a choice, `.lino-grid` for tiles) |
+| An app's menus | `Menubar` |
+| Text in | `Input` with a `Label` |
+| A number in a range | `Slider` |
+| A decision that stops the flow | `Dialog` (title, description, footer with the actions) |
+| A shortcut | `Kbd keys="mod shift z"` |
+| Something is loading | `Spinner` with `aria-label` |
+| A rank or tier | `Tag`, a framed `Picture`, a `Plaque` |
+| A break between groups | `Separator` (rarely) |
+| A panel, card or section of your own | a `div` with `{@attach cut('plate')}` and `--surface-bg` (Texture, below) |
+
+```svelte
+<script>
+  import { Button } from "lino-ui/button";
+  import * as Tooltip from "lino-ui/tooltip";
+  import { icon } from "lino-ui";
+</script>
+
+<Tooltip.Provider>
+  <Tooltip.Root>
+    <Tooltip.Trigger>
+      {#snippet child({ props })}
+        <Button {...props} size="icon" aria-label="Search">{@html icon("search")}</Button>
+      {/snippet}
+    </Tooltip.Trigger>
+    <Tooltip.Content sideOffset={8}>Search</Tooltip.Content>
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+## Do
+
+- Use the kit's component whenever there is one, as its page shows it. Its props are the API; `class` adds layout
+  (margins, grid placement), never a new look.
+- Colours, type, space and motion are tokens (`src/ds/tokens.css`): `--color-background` (paper), `--color-text`
+  (ink), `--color-surface` (plates), `--color-accent` (on, primary, focus), `--color-muted` (captions, shortcuts),
+  `--color-border`, `--color-divider`. A hover, a pressed state or a tint is `color-mix()` of tokens where it is used:
+  `color-mix(in srgb, var(--color-text) 6%, var(--color-surface))`.
+- The chrome speaks Alegreya Sans SC (`--font-display`): buttons, menus, labels, titles. Inter (`--font-text`) only for
+  running text. Sizes `--text-xs` 14 … `--text-2xl` 56px.
+- Accent orange means "on" or "primary": one accent action per view, a switch that is on, the focus ring.
+- Every white surface on the paper gets the border: `--surface-border: var(--color-border)`.
+- Name every icon-only control (`aria-label`) and show the name, with the shortcut, in a tooltip.
+- Keep the keyboard: every control is reachable, focus rings stay whole (`outline: var(--focus-ring)`).
+- Motion: short fades and 4px slides with `--dur` and `--ease-out`; a press shrinks by `--press` (the kit does it).
+
+## Don't
+
+- **No CSS `border`, `border-radius`, `box-shadow` or `filter`.** Not on anything. No pills, no rounded corners, no
+  circles in rectangles, no elevation. A surface separates from the paper by its fill and a cut border.
+- No hex colours and no new colour tokens: `hsl()` tokens and `color-mix()` of them. A colour written as a value
+  (`white`, `#fff`, `hsl(0 0% 100%)`) breaks the dark themes; `--color-surface` is white only in Solar.
+- No translucent colour on an icon: its stroke darkens where it overlaps. Use an opaque token (`--color-muted`).
+- No inline SVG icons, icon fonts, lucide or emoji as icons. Icons are `icon(name)`; a new one is baked (Icons).
+- No decoration: no glyph that means nothing, no divider for looks, no control the screen doesn't need now.
+- Hover never moves anything: one tint step, a quiet label to full ink. No scale, no translate on hover.
+- Layout never lives only on an open state (`[data-state=open]`): what fades out would jump.
+- Never copy a mockup's frames, badges, numerals or icons as pictures. From a mockup take only photos and
+  illustrations; everything else is built with the kit.
+- Never outline text. Text is real text.
+
+## Texture: when to cut, and with what
+
+Every surface and border in lino is cut, like paper trimmed with scissors. A cut is a vector outline displaced by
+noise: no filter, no image of an edge. Decide by what the thing is:
+
+| It is | Cut? | How |
+|---|---|---|
+| A kit component (button, menu, dialog, toolbar, tag…) | Already cut | Nothing. Don't add a border or a fill to it |
+| A panel, card, section, popover, list box or code block you compose, 32px or more | Yes | `{@attach cut('plate')}` from `lino-ui`; set `--surface-bg`, and `--surface-border` for a border |
+| A strip, chip or field of your own, 16–32px high | Yes | `{@attach cut('chip')}` |
+| A label with a thick border | Yes | `{@attach cut('tag')}`, or the kit's `Tag` |
+| A badge, frame, medal, tile, ticket, any shape that is not a plain rectangle, a piece of art | Yes | Skill **lino-texture**: a fixed shape is cut with `texturize` (or baked); one that resizes is an n-slice surface |
+| A new icon | Yes, baked | `npx lino icon <file.svg>` (Icons) |
+| A photo or an illustration | Not the picture | Clip it with a cut shape (`clip-path`), the picture untouched; or the kit's `Picture` |
+| Text | Never | Real text on top of the cut |
+| A layout wrapper with no fill (a row, a grid, a column) | No | Nothing to cut: it has no edge |
+| A plate inside a plate | No | One surface per level: drop the inner fill, group by space |
+| The page's paper | No | `--color-background` on `body` |
+| A divider | Already cut | `Separator` (a cut strip, `--rough-rule`) |
+| A focus ring | No | `outline: var(--focus-ring)`, never clipped (the fill sits on a layer behind the content) |
+
+A plate of your own:
+
+```svelte
+<script>
+  import { cut } from "lino-ui";
+</script>
+
+<section class="card" {@attach cut("plate")}>…</section>
+
+<style>
+  .card { --surface-bg: var(--color-surface); --surface-border: var(--color-border); padding: var(--space-6); }
+</style>
+```
+
+Neighbouring plates get different seeds by themselves. A state changes `--surface-bg` / `--surface-border` only; the
+outline never changes.
+
+## Icons
+
+`icon(name)` from `lino-ui` returns the `<svg>` markup: `{@html icon("search")}`. It is coloured by `currentColor`,
+sized by its glyph, and in the kit's buttons, toggles and menu rows it is sized and weighted for you: beside a label
+`.8em`, 12px from it, as heavy as the label's letters; alone 20, 24 or 26px on a 32, 40 or 56px control. `ICON_NAMES()`
+lists the set.
+
+A new icon is never drawn in code. Get the vector (a Figma export with strokes, not outlined) and bake it:
+
+```bash
+npx lino icon design/icons/*.svg --out src/lib/icons.js
+```
+
+It cuts every glyph at the one icon weight with the hand-cut texture. Import the output once in the app's entry
+(`import "./lib/icons.js"`): it registers the icons, and `icon("<file name>")` draws them. Skill **lino-ui**, Icons.
+
+## Skills: which one when
+
+| Skill | Use it for |
+|---|---|
+| **lino-ui** | Any interface work with the kit: a screen, a panel, a form, a menu, a dialog, choosing a component, an icon, "in lino's style" |
+| **lino-texture** | A shape the kit doesn't have: a badge, a frame, a plaque, a tile, a decorative plate, art, a surface that stretches (n-slice) |
+
+`npx lino init` installs them for Claude Code (`.claude/skills`). Any other agent reads them from
+`skills/<name>/SKILL.md`.
+
+## Verify
+
+Look at it in the browser before you call it done: a zoomed screenshot of every edge (cut, never straight, no seams)
+and of the spacing; measure paddings on the cut edge, not the box; tab through it with the keyboard; check that every
+icon-only control has a name. Then tell the user what to look at, and that the docs are at the URL `lino docs` gave.
+
+## The CLI
+
+| Command | Does |
+|---|---|
+| `npx lino docs [--port 4977] [--detach]` | Serves the documentation site; `--detach` leaves it running and prints its URL |
+| `npx lino init` | Gives the project's agents this guide: skills, the AGENTS.md / CLAUDE.md block, the session hook |
+| `npx lino icon <svg…> [--out file.js]` | Bakes SVG vectors into hand-cut icons for `icon()` |
+| `npx lino surface <specs.mjs> <out.js>` | Bakes n-slice surfaces (skill lino-texture) |
+
+## Where things are
+
+| Path | What |
+|---|---|
+| `docs/` | Every page of the site as Markdown: `llms.txt` (the index), `llms-full.txt` (all), `<page>.md` |
+| `skills/` | The agent skills |
+| `src/ds/PRINCIPLES.md` | The full rules, with their reasons |
+| `src/lib/components/ui/` | The components' source |
+| `src/lib/lino.css`, `src/ds/tokens.css` | The look and the tokens |
+| `site/` | The documentation site that `lino docs` serves |

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# lino-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.
+Svelte 5 components in lino's look: paper, ink, one accent, and every edge cut by hand, like paper trimmed with
+scissors. Focus, keyboard and screen-reader behaviour come with them.
+
+```bash
+npm i lino-ui
+npx lino init     # the guide, the skills and a session hook for the project's agents
+npx lino docs     # the documentation site, on http://localhost:4977
+```
+
+In the app's entry (SvelteKit: the root `+layout.svelte`):
+
+```js
+import "lino-ui/styles.css";
+import "lino-ui/setup";
+```
+
+```svelte
+<script>
+  import { Button } from "lino-ui/button";
+</script>
+
+<Button variant="accent">Publish</Button>
+```
+
+- [AGENTS.md](AGENTS.md): how to build with it, what never to do, when to cut a texture, which skill when. For agents
+  and people alike.
+- `docs/`: every page of the documentation as Markdown (`docs/llms.txt` is the index).
+- `skills/`: lino-ui (building interface) and lino-texture (new hand-cut shapes).

package/bin/lino.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// The lino-ui command line (AGENTS.md, The CLI):
+//   lino docs [--port 4977] [--detach]   serve the documentation site (./site); --detach leaves it running
+//   lino init [--no-hook]                give the project's agents the guide, the skills and the session hook
+//   lino icon <svg…> [--out file.js]     bake vectors into hand-cut icons for icon()
+//   lino surface <specs.mjs> <out.js>    bake n-slice surfaces
+// No dependencies: Node's own http, fs, child_process.
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const { name: NAME, version: VERSION } = JSON.parse(readFileSync(join(PKG, 'package.json'), 'utf8'));
+const args = process.argv.slice(2);
+const cmd = args.shift();
+const flag = (k, d) => { const i = args.indexOf(k); return i < 0 ? d : args.splice(i, 2)[1]; };
+const has = (k) => { const i = args.indexOf(k); return i >= 0 && args.splice(i, 1).length > 0; };
+const die = (msg) => { console.error(msg); process.exit(1); };
+
+// ---------- docs: the site, on the first free port from 4977; the same server again while it runs ----------
+const TYPES = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.txt': 'text/plain',
+  '.md': 'text/markdown', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.ico': 'image/x-icon', '.woff2': 'font/woff2',
+  '.mp3': 'audio/mpeg', '.webmanifest': 'application/manifest+json' };
+const SITE = join(PKG, 'site');
+const say = (url) => console.log(`lino-ui docs: ${url}\nThe documentation site (every component live, its examples and props, the rules for building with lino-ui) is running there. Tell the user they can open it.`);
+
+// what answers on a port: this package's docs server, another, or nothing
+async function probe(port) {
+  try {
+    const r = await fetch(`http://localhost:${port}/__lino`, { signal: AbortSignal.timeout(500) });
+    const info = r.ok ? await r.json().catch(() => null) : null;
+    return info?.site === SITE ? 'ours' : 'taken';
+  } catch (e) { return e.cause?.code === 'ECONNREFUSED' ? 'free' : 'taken'; }
+}
+
+async function docs() {
+  const first = +flag('--port', 4977), detach = has('--detach');
+  if (!existsSync(join(SITE, 'index.html'))) die(`no site in ${SITE}: is ${NAME} built?`);
+  for (let port = first; port < first + 20; port++) {
+    const state = await probe(port);
+    if (state === 'ours') return say(`http://localhost:${port}/`);
+    if (state === 'taken') continue;
+    if (detach) {
+      spawn(process.execPath, [fileURLToPath(import.meta.url), 'docs', '--port', String(port)], { detached: true, stdio: 'ignore' }).unref();
+      for (let i = 0; i < 50; i++) {
+        await new Promise((r) => setTimeout(r, 100));
+        if (await probe(port) === 'ours') return say(`http://localhost:${port}/`);
+      }
+      die(`the docs server did not start on ${port}`);
+    }
+    return serve(port);
+  }
+  die(`no free port from ${first} to ${first + 19}`);
+}
+
+function serve(port) {
+  createServer((req, res) => {
+    const path = decodeURIComponent(new URL(req.url, 'http://x').pathname);
+    if (path === '/__lino') return res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ name: NAME, version: VERSION, site: SITE }));
+    let file = resolve(SITE, '.' + path);
+    if (!file.startsWith(SITE + sep) && file !== SITE) return res.writeHead(403).end();
+    if (existsSync(file) && statSync(file).isDirectory()) file = join(file, 'index.html');
+    if (!existsSync(file)) return res.writeHead(404, { 'content-type': 'text/plain' }).end('not found');
+    const type = TYPES[extname(file)] ?? 'application/octet-stream';
+    res.writeHead(200, { 'content-type': type.startsWith('text/') || type.includes('json') ? `${type}; charset=utf-8` : type });
+    res.end(readFileSync(file));
+  }).listen(port, () => say(`http://localhost:${port}/`));
+}
+
+// ---------- init: the guide, the skills and the hook in the project (run again after an update) ----------
+const START = '<!-- lino-ui:start (written by `npx lino init`; run it again after updating lino-ui) -->', END = '<!-- lino-ui:end -->';
+
+function init() {
+  const root = process.cwd(), pkg = relative(root, PKG).split(sep).join('/'), noHook = has('--no-hook');
+  const block = `${START}
+## Interface: lino-ui
+
+The interface is built with lino-ui. Before any UI work read \`${pkg}/AGENTS.md\` and follow it: what to do and what
+never to do, which component for which need, when to cut a texture.
+
+- At the start of a session, and whenever you start the app's dev server, run \`npx lino docs --detach\` and tell the
+  user the URL it prints: the documentation site, with every component, its examples and the rules.
+- Skills: **lino-ui** for any interface work, **lino-texture** for a new hand-cut shape. Their files:
+  \`${pkg}/skills/\`.
+${END}`;
+  const put = (file, text) => { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, text); console.log('wrote', relative(root, file)); };
+  const withBlock = (text) => text.includes(START) ? text.replace(new RegExp(`${START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${END}`), block) : `${text.trimEnd()}${text.trim() ? '\n\n' : ''}${block}\n`;
+
+  // the skills: Claude Code finds them in .claude/skills; each is a pointer to the package's file, so it updates with it
+  for (const name of readdirSync(join(PKG, 'skills'))) {
+    const src = readFileSync(join(PKG, 'skills', name, 'SKILL.md'), 'utf8'), front = src.match(/^---\n[\s\S]*?\n---\n/)[0];
+    put(join(root, '.claude/skills', name, 'SKILL.md'), `${front}
+This skill ships with lino-ui, and lives in the package so it is always the installed version's. Read
+\`${pkg}/skills/${name}/SKILL.md\` now and follow it; its references are beside it.
+`);
+  }
+
+  // the block in AGENTS.md (other agents read it); CLAUDE.md imports AGENTS.md, or carries the block itself
+  const agents = join(root, 'AGENTS.md'), claude = join(root, 'CLAUDE.md');
+  put(agents, withBlock(existsSync(agents) ? readFileSync(agents, 'utf8') : ''));
+  if (!existsSync(claude)) put(claude, '@AGENTS.md\n');
+  else if (!/^@AGENTS\.md\s*$/m.test(readFileSync(claude, 'utf8'))) put(claude, withBlock(readFileSync(claude, 'utf8')));
+
+  // Claude Code: start the docs with every session, and tell the agent where they are (a SessionStart hook's output)
+  if (!noHook) {
+    const file = join(root, '.claude/settings.json'), settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    const command = 'npx --no-install lino docs --detach';
+    const starts = ((settings.hooks ??= {}).SessionStart ??= []);
+    if (!starts.some((g) => g.hooks?.some((h) => h.command === command))) {
+      starts.push({ hooks: [{ type: 'command', command }] });
+      put(file, JSON.stringify(settings, null, 2) + '\n');
+    }
+  }
+  console.log(`\nDone. Agents read ${pkg}/AGENTS.md; the docs start with each Claude Code session (npx lino docs).`);
+}
+
+// ---------- icon: an app's own icons, cut like the kit's, into a module that registers them ----------
+async function icons() {
+  const out = resolve(flag('--out', 'src/lib/icons.js')), files = args.filter((a) => a.endsWith('.svg'));
+  if (!files.length) die('usage: lino icon <file.svg…> [--out src/lib/icons.js]');
+  const { cutIcon, iconsModule, ROW } = await import(pathToFileURL(join(PKG, 'src/ds/icon-bake.js')).href);
+  // the icons already in the module stay, unless baked again now
+  const icons = {};
+  if (existsSync(out)) for (const m of readFileSync(out, 'utf8').matchAll(/^ {2}'?([\w-]+)'?: \{ viewBox: \[([^\]]*)\], ink: \[([^\]]*)\], d: '([^']*)' \},$/gm))
+    icons[m[1]] = { viewBox: m[2].split(', ').map(Number), ink: m[3].split(', ').map(Number), d: m[4] };
+  for (const file of files) {
+    const svg = readFileSync(file, 'utf8'), name = basename(file, '.svg');
+    // its own texture if the export carries one (Figma's TEXTURE effect), the kit's tools row's otherwise
+    const icon = icons[name] = cutIcon(svg, { textures: /feTurbulence/.test(svg) ? [] : [ROW] });
+    console.log(`${name}: ${icon.loops} loops, ${icon.d.length} chars`);
+  }
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, iconsModule(icons, { name: 'ICONS', register: NAME, header: `// Baked by \`npx lino icon\` (lino-ui) from SVG vectors: do not edit, bake again. Import it once in the app's entry;
+// then icon("<name>") draws each, cut by hand at the one icon weight.
+` }));
+  console.log('wrote', relative(process.cwd(), out));
+}
+
+// ---------- surface: n-slice surfaces (skill lino-texture) ----------
+async function surface() {
+  const name = flag('--name', 'SURFACES'), [specPath, outPath] = args;
+  if (!specPath || !outPath) die('usage: lino surface <specs.mjs> <out.js> [--name SURFACES]');
+  const { bakeNSlice } = await import(pathToFileURL(join(PKG, 'src/ds/nslice.js')).href);
+  const specs = (await import(pathToFileURL(resolve(specPath)).href)).default, out = {};
+  for (const [key, spec] of Object.entries(specs)) {
+    const t0 = performance.now(), b = out[key] = bakeNSlice(spec);
+    console.log(`${key}: master ${b.w}×${b.h}, layers ${b.layers.length}, ${(JSON.stringify(b).length / 1024).toFixed(1)} KB, ${Math.round(performance.now() - t0)} ms`);
+  }
+  writeFileSync(outPath, `// Baked by \`npx lino surface\` (lino-ui) from ${relative(dirname(resolve(outPath)), resolve(specPath))}: do not edit, bake again.
+// N-slice surfaces cut by hand: mountCut(el, ${name}.<name>) from "lino-ui/nslice" keeps one on an element at any size.
+export const ${name} = ${JSON.stringify(out)};
+`);
+  console.log('wrote', outPath);
+}
+
+const COMMANDS = { docs, init, icon: icons, surface };
+if (!COMMANDS[cmd]) {
+  console.log(`lino-ui ${VERSION}
+  lino docs [--port 4977] [--detach]   serve the documentation site; --detach leaves it running
+  lino init [--no-hook]                give this project's agents the guide, the skills and the session hook
+  lino icon <svg…> [--out file.js]     bake vectors into hand-cut icons for icon()
+  lino surface <specs.mjs> <out.js>    bake n-slice surfaces
+The guide: ${relative(process.cwd(), join(PKG, 'AGENTS.md'))}`);
+  process.exit(cmd && cmd !== 'help' && cmd !== '--help' ? 1 : 0);
+}
+await COMMANDS[cmd]();

package/docs/agents.md

@@ -0,0 +1,230 @@
+# Agents
+
+How an agent builds interface with the kit: what to do, what never to do, when to cut a texture, which skill when. The package's AGENTS.md.
+
+For agents (and people) who build screens with `lino-ui`: Svelte 5 components in lino's look, paper, ink, one
+accent, every edge cut by hand. Read this file whole before the first piece of UI; it is short, and every rule in it
+comes from review. Paths below are relative to the package (`node_modules/lino-ui/`).
+
+## At the start of every session
+
+1. Start the documentation site and tell the user where it is:
+
+   ```bash
+   npx lino docs --detach
+   ```
+
+   It prints a local URL (the same one while it runs; it starts once). Say to the user, in their language, something
+   like: "The lino-ui docs are open at http://localhost:4977: every component with live examples, its props and
+   these rules." Do it again whenever you start the app's dev server, if it is not running.
+2. Read this file. Before you use a component, read its page: `docs/<component>.md` (`docs/button.md`), or the same at
+   `<docs URL>/ds/<component>/llms.txt`. The index of every page is `docs/llms.txt`.
+
+## Setting up an app
+
+Svelte 5 with Vite (SvelteKit or plain). Once:
+
+```bash
+npm i lino-ui
+npx lino init
+```
+
+`lino init` gives the project's agents this guide: the skills (`.claude/skills`, pointers into the package, so they
+update with it), a block in `AGENTS.md` and `CLAUDE.md`, and a Claude Code hook that starts the docs with each session.
+Then, in the app's entry (SvelteKit: the root `+layout.svelte`):
+
+```js
+import "lino-ui/styles.css"; // tokens, fonts, the kit's look
+import "lino-ui/setup";      // the rough cuts, the press, the interface sounds
+```
+
+The page's background is the paper: `body { background: var(--color-background); color: var(--color-text); }`.
+
+Three themes, only the colours change: Solar (light, the default), and the dark Ink and Lunar on
+`<html data-theme="ink">` / `"lunar"`. Set the attribute before the first paint (a line of script in `<head>`), so a
+dark theme never flashes paper. Everything you build follows by itself as long as it takes its colours from tokens.
+
+## Building from a prompt
+
+1. **Read the request as surfaces, controls, content.** Surfaces are what things sit on (a panel, a menu, a dialog,
+   a card). Controls are what the user acts on. Content is text, pictures, numbers. Icons belong to controls.
+2. **Pick a component for every control and surface** (the table below). Compose; never restyle a component into
+   another one.
+3. **Lay it out on the 4px grid.** Spaces are `--space-1` 4px … `--space-8` 32px. Hug the content, the same padding
+   on every side, one height and one centre line for everything on a bar.
+4. **One surface per level.** A control on a plate uses that plate; it never brings its own fill inside it. Group by
+   space first; a separator only between real groups.
+5. **Check the list of don'ts**, then look at it in the browser (see Verify).
+
+### Which component
+
+| The user needs | Use |
+|---|---|
+| An action | `Button`: `variant="action"` on a surface, `"panel"` straight on the paper, `"accent"` for the one primary action of a view, `"ghost"` for quiet ones |
+| An action shown as an icon | `Button size="icon"` (`icon-sm`, `icon-lg`) with `aria-label`, inside a `Tooltip` with its name and shortcut |
+| Several actions joined | `ButtonGroup` |
+| On / off | `Switch` with a `Label` |
+| One of a few, all visible | `ToggleGroup` (a track); a pressed state on one button: `Toggle` |
+| A set of tools | `Toolbar` holding a `ToggleGroup variant="bare" size="icon"` |
+| One of many, or actions behind a button | `DropdownMenu` (radio items for a choice, `.lino-grid` for tiles) |
+| An app's menus | `Menubar` |
+| Text in | `Input` with a `Label` |
+| A number in a range | `Slider` |
+| A decision that stops the flow | `Dialog` (title, description, footer with the actions) |
+| A shortcut | `Kbd keys="mod shift z"` |
+| Something is loading | `Spinner` with `aria-label` |
+| A rank or tier | `Tag`, a framed `Picture`, a `Plaque` |
+| A break between groups | `Separator` (rarely) |
+| A panel, card or section of your own | a `div` with `{@attach cut('plate')}` and `--surface-bg` (Texture, below) |
+
+```svelte
+<script>
+  import { Button } from "lino-ui/button";
+  import * as Tooltip from "lino-ui/tooltip";
+  import { icon } from "lino-ui";
+</script>
+
+<Tooltip.Provider>
+  <Tooltip.Root>
+    <Tooltip.Trigger>
+      {#snippet child({ props })}
+        <Button {...props} size="icon" aria-label="Search">{@html icon("search")}</Button>
+      {/snippet}
+    </Tooltip.Trigger>
+    <Tooltip.Content sideOffset={8}>Search</Tooltip.Content>
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+## Do
+
+- Use the kit's component whenever there is one, as its page shows it. Its props are the API; `class` adds layout
+  (margins, grid placement), never a new look.
+- Colours, type, space and motion are tokens (`src/ds/tokens.css`): `--color-background` (paper), `--color-text`
+  (ink), `--color-surface` (plates), `--color-accent` (on, primary, focus), `--color-muted` (captions, shortcuts),
+  `--color-border`, `--color-divider`. A hover, a pressed state or a tint is `color-mix()` of tokens where it is used:
+  `color-mix(in srgb, var(--color-text) 6%, var(--color-surface))`.
+- The chrome speaks Alegreya Sans SC (`--font-display`): buttons, menus, labels, titles. Inter (`--font-text`) only for
+  running text. Sizes `--text-xs` 14 … `--text-2xl` 56px.
+- Accent orange means "on" or "primary": one accent action per view, a switch that is on, the focus ring.
+- Every white surface on the paper gets the border: `--surface-border: var(--color-border)`.
+- Name every icon-only control (`aria-label`) and show the name, with the shortcut, in a tooltip.
+- Keep the keyboard: every control is reachable, focus rings stay whole (`outline: var(--focus-ring)`).
+- Motion: short fades and 4px slides with `--dur` and `--ease-out`; a press shrinks by `--press` (the kit does it).
+
+## Don't
+
+- **No CSS `border`, `border-radius`, `box-shadow` or `filter`.** Not on anything. No pills, no rounded corners, no
+  circles in rectangles, no elevation. A surface separates from the paper by its fill and a cut border.
+- No hex colours and no new colour tokens: `hsl()` tokens and `color-mix()` of them. A colour written as a value
+  (`white`, `#fff`, `hsl(0 0% 100%)`) breaks the dark themes; `--color-surface` is white only in Solar.
+- No translucent colour on an icon: its stroke darkens where it overlaps. Use an opaque token (`--color-muted`).
+- No inline SVG icons, icon fonts, lucide or emoji as icons. Icons are `icon(name)`; a new one is baked (Icons).
+- No decoration: no glyph that means nothing, no divider for looks, no control the screen doesn't need now.
+- Hover never moves anything: one tint step, a quiet label to full ink. No scale, no translate on hover.
+- Layout never lives only on an open state (`[data-state=open]`): what fades out would jump.
+- Never copy a mockup's frames, badges, numerals or icons as pictures. From a mockup take only photos and
+  illustrations; everything else is built with the kit.
+- Never outline text. Text is real text.
+
+## Texture: when to cut, and with what
+
+Every surface and border in lino is cut, like paper trimmed with scissors. A cut is a vector outline displaced by
+noise: no filter, no image of an edge. Decide by what the thing is:
+
+| It is | Cut? | How |
+|---|---|---|
+| A kit component (button, menu, dialog, toolbar, tag…) | Already cut | Nothing. Don't add a border or a fill to it |
+| A panel, card, section, popover, list box or code block you compose, 32px or more | Yes | `{@attach cut('plate')}` from `lino-ui`; set `--surface-bg`, and `--surface-border` for a border |
+| A strip, chip or field of your own, 16–32px high | Yes | `{@attach cut('chip')}` |
+| A label with a thick border | Yes | `{@attach cut('tag')}`, or the kit's `Tag` |
+| A badge, frame, medal, tile, ticket, any shape that is not a plain rectangle, a piece of art | Yes | Skill **lino-texture**: a fixed shape is cut with `texturize` (or baked); one that resizes is an n-slice surface |
+| A new icon | Yes, baked | `npx lino icon <file.svg>` (Icons) |
+| A photo or an illustration | Not the picture | Clip it with a cut shape (`clip-path`), the picture untouched; or the kit's `Picture` |
+| Text | Never | Real text on top of the cut |
+| A layout wrapper with no fill (a row, a grid, a column) | No | Nothing to cut: it has no edge |
+| A plate inside a plate | No | One surface per level: drop the inner fill, group by space |
+| The page's paper | No | `--color-background` on `body` |
+| A divider | Already cut | `Separator` (a cut strip, `--rough-rule`) |
+| A focus ring | No | `outline: var(--focus-ring)`, never clipped (the fill sits on a layer behind the content) |
+
+A plate of your own:
+
+```svelte
+<script>
+  import { cut } from "lino-ui";
+</script>
+
+<section class="card" {@attach cut("plate")}>…</section>
+
+<style>
+  .card { --surface-bg: var(--color-surface); --surface-border: var(--color-border); padding: var(--space-6); }
+</style>
+```
+
+Neighbouring plates get different seeds by themselves. A state changes `--surface-bg` / `--surface-border` only; the
+outline never changes.
+
+## Icons
+
+`icon(name)` from `lino-ui` returns the `<svg>` markup: `{@html icon("search")}`. It is coloured by `currentColor`,
+sized by its glyph, and in the kit's buttons, toggles and menu rows it is sized and weighted for you: beside a label
+`.8em`, 12px from it, as heavy as the label's letters; alone 20, 24 or 26px on a 32, 40 or 56px control. `ICON_NAMES()`
+lists the set.
+
+A new icon is never drawn in code. Get the vector (a Figma export with strokes, not outlined) and bake it:
+
+```bash
+npx lino icon design/icons/*.svg --out src/lib/icons.js
+```
+
+It cuts every glyph at the one icon weight with the hand-cut texture. Import the output once in the app's entry
+(`import "./lib/icons.js"`): it registers the icons, and `icon("<file name>")` draws them. Skill **lino-ui**, Icons.
+
+## Skills: which one when
+
+| Skill | Use it for |
+|---|---|
+| **lino-ui** | Any interface work with the kit: a screen, a panel, a form, a menu, a dialog, choosing a component, an icon, "in lino's style" |
+| **lino-texture** | A shape the kit doesn't have: a badge, a frame, a plaque, a tile, a decorative plate, art, a surface that stretches (n-slice) |
+
+`npx lino init` installs them for Claude Code (`.claude/skills`). Any other agent reads them from
+`skills/<name>/SKILL.md`.
+
+## Verify
+
+Look at it in the browser before you call it done: a zoomed screenshot of every edge (cut, never straight, no seams)
+and of the spacing; measure paddings on the cut edge, not the box; tab through it with the keyboard; check that every
+icon-only control has a name. Then tell the user what to look at, and that the docs are at the URL `lino docs` gave.
+
+## The CLI
+
+| Command | Does |
+|---|---|
+| `npx lino docs [--port 4977] [--detach]` | Serves the documentation site; `--detach` leaves it running and prints its URL |
+| `npx lino init` | Gives the project's agents this guide: skills, the AGENTS.md / CLAUDE.md block, the session hook |
+| `npx lino icon <svg…> [--out file.js]` | Bakes SVG vectors into hand-cut icons for `icon()` |
+| `npx lino surface <specs.mjs> <out.js>` | Bakes n-slice surfaces (skill lino-texture) |
+
+## Where things are
+
+| Path | What |
+|---|---|
+| `docs/` | Every page of the site as Markdown: `llms.txt` (the index), `llms-full.txt` (all), `<page>.md` |
+| `skills/` | The agent skills |
+| `src/ds/PRINCIPLES.md` | The full rules, with their reasons |
+| `src/lib/components/ui/` | The components' source |
+| `src/lib/lino.css`, `src/ds/tokens.css` | The look and the tokens |
+| `site/` | The documentation site that `lino docs` serves |
+
+
+## This site as Markdown
+
+Every page of this site is also Markdown for language models, after the llms.txt convention: **Copy Markdown** on each
+page, its file `/ds/<page>/llms.txt`, the index `llms.txt`, everything in one file `llms-full.txt`. In the package
+the same files are in `docs/`.
+
+## The skills' files
+
+- **lino-texture** (`../skills/lino-texture/SKILL.md`): Cut new shapes by hand for lino-ui: badges, frames, plaques, tiles, tickets, medals, decorative plates, art, and surfaces that stretch to any size (n-slice / 9-slice / 3-slice), with lino's vector texture (texturize, bakeNSlice, mountCut from lino-ui).
+- **lino-ui** (`../skills/lino-ui/SKILL.md`): Build interface with lino-ui, the Svelte 5 kit in lino's hand-cut look (paper, ink, one accent, every edge cut by hand).