@uidu/skills 0.4.0 → 0.6.0

package/README.md

@@ -14,9 +14,10 @@ Replace `claude-code` with your agent of choice (`cursor`, `copilot`, `windsurf`
 
 ## Available skills
 
-| Skill | Description |
-|---|---|
-| `uidu` | Comprehensive guide to the uidu SDK — package map, env setup, fetch patterns for CMS pages, events, stories, donations, help center, and forms, plus RichText rendering and scaffolding via `create-uidu-app`. |
+| Skill         | Description                                                                                                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `uidu`        | Comprehensive guide to the uidu SDK — package map, env setup, fetch patterns for CMS pages, events, stories, donations, help center, and forms, plus RichText rendering and scaffolding via `create-uidu-app`.  |
+| `uidu-design` | How an app framed inside uidu (a custom app) should look: uidu's tokens and components, layout inside the iframe, states, icons. Ships inside the `custom-app` template, so the app builder's agent has it too. |
 
 More skills will be split out from `uidu` as individual areas grow.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uidu/skills",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Agent skills for the uidu SDK — installable via the open agent skills ecosystem (skills.sh).",
   "license": "MIT",
   "author": "uidu",

package/skills/uidu/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: uidu
-description: Use when building on the uidu platform — a public website or an app that runs inside uidu (a custom app in a Space or workspace); reading CMS pages, events, stories, donations, help center, forms; rendering WYSIWYG content; scaffolding projects; OR provisioning/authoring uidu content (create/update/delete) from the terminal via the @uidu/cli (`uidu`). Triggers on any task involving uidu, the @uidu/client SDK, @uidu/react bindings, or the uidu CLI.
+description: Use when building on the uidu platform — a public website or an app that runs inside uidu (a custom app in a Space or workspace); reading CMS pages, events, stories, donations, help center, forms, or the workspace's own data (goals/OKRs, contacts, deals, people); rendering WYSIWYG content; scaffolding projects; OR provisioning/authoring uidu content (create/update/delete) from the terminal via the @uidu/cli (`uidu`). Triggers on any task involving uidu, the @uidu/client SDK, @uidu/react bindings, or the uidu CLI.
 license: MIT
 metadata:
   author: uidu
-  version: "0.5.0"
+  version: '0.6.0'
 ---
 
 # uidu SDK
@@ -13,7 +13,7 @@ The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powe
 
 - **`@uidu/client`** — framework-agnostic GraphQL client. Safe for server-side use (RSC, route handlers, server actions, scripts).
 - **`@uidu/app-bridge`** — the browser half of a custom app: the handshake with the uidu page that frames it, and its short-lived session token. Only for apps that run inside uidu.
-- **`@uidu/react`** — React hooks (`useUiduClient`, `useQuery`, `useFields`, `toText`, `useUiduApp`) and components (`<UiduAppProvider>`, `<PageBlocks>`, `<BlockRenderer>`, `<RichText>`, `<DynamicForm>`). That list is the **complete** public surface — there is no `useForm`, `usePage` or `useChannel`; for anything else, call a `@uidu/client` function.
+- **`@uidu/react`** — React hooks (`useUiduClient`, `useQuery`, `useFields`, `toText`, `useUiduApp`) and components (`<UiduAppProvider>`, `<PageBlocks>`, `<BlockRenderer>`, `<RichText>`, `<DynamicForm>`). That list is the **complete** public surface — there is no `useForm`, `usePage` or `useChannel`; for anything else, call a `@uidu/client` function. `@uidu/client` has one for each entity uidu already holds (goals, contacts, deals, people, events… — see [Workspace data](#workspace-data)): look there before writing a query or creating a Model.
 
 `@uidu/api.js` is a legacy bridge package and is **deprecated** — use `@uidu/react` directly.
 
@@ -31,12 +31,12 @@ Use this skill when the user is:
 
 ## Package Map
 
-| Package | When to use | Notes |
-|---|---|---|
-| `@uidu/client` | Server-side queries (RSC, server actions, scripts) | Framework-agnostic |
-| `@uidu/react` | React hooks, providers, and components | Some hooks are client-only |
-| `@uidu/app-bridge` | An app that runs inside uidu (custom app) | Browser only; in React use `<UiduAppProvider>` |
-| `@uidu/api.js` | **Do not use for new code.** | Deprecated; re-exports `@uidu/react` |
+| Package            | When to use                                        | Notes                                          |
+| ------------------ | -------------------------------------------------- | ---------------------------------------------- |
+| `@uidu/client`     | Server-side queries (RSC, server actions, scripts) | Framework-agnostic                             |
+| `@uidu/react`      | React hooks, providers, and components             | Some hooks are client-only                     |
+| `@uidu/app-bridge` | An app that runs inside uidu (custom app)          | Browser only; in React use `<UiduAppProvider>` |
+| `@uidu/api.js`     | **Do not use for new code.**                       | Deprecated; re-exports `@uidu/react`           |
 
 Install:
 
@@ -80,14 +80,14 @@ reports `does not support <verb>` when it doesn't. Config resolves **flags → e
 
 ## Who the app acts for — one rule
 
-What an app *looks like* (landing page, blog, dashboard, booking tool) changes nothing.
+What an app _looks like_ (landing page, blog, dashboard, booking tool) changes nothing.
 What changes the code is **who the request acts for**:
 
-| Operation | Auth | Where it runs |
-|---|---|---|
-| **Reads** for anyone (`get*` / `list*`, `<entity> list/get`) | `publicToken` | anywhere — server, CLI, **and the browser** |
-| **Writes** as the workspace (`create*` / `update*` / `delete*`, `<entity> create/update/delete`) | account **Bearer** (`apiKey`) | CLI and **server-side** only |
-| **Anything as the signed-in member**, inside uidu (a custom app) | session token from the host, over `@uidu/app-bridge` | **the browser only** |
+| Operation                                                                                        | Auth                                                 | Where it runs                               |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------- |
+| **Reads** for anyone (`get*` / `list*`, `<entity> list/get`)                                     | `publicToken`                                        | anywhere — server, CLI, **and the browser** |
+| **Writes** as the workspace (`create*` / `update*` / `delete*`, `<entity> create/update/delete`) | account **Bearer** (`apiKey`)                        | CLI and **server-side** only                |
+| **Anything as the signed-in member**, inside uidu (a custom app)                                 | session token from the host, over `@uidu/app-bridge` | **the browser only**                        |
 
 The write functions live in `@uidu/client`, so anything the CLI provisions you can also do
 from a Next.js server action / route handler / RSC. **Never put the account Bearer token in a
@@ -111,10 +111,13 @@ that person can do, and no more. It changes five things:
    needs a server credential uidu doesn't issue yet.
 3. **Treat the token as opaque.** Never decode it. The expiry comes with it, the bridge refreshes
    it, and `graphqlUrl` comes with it too: never build `https://<workspace>.uidu.org` from a slug.
-4. **Data goes in the app's own Models.** The session reaches the app's own Models, fields and
-   items through `node(id:)`, and the data-engine mutations. Everything else in the workspace comes
-   back as an error. Keep your data there rather than in a database of your own: it stays
-   searchable and permissioned in uidu.
+4. **Read what the workspace already has; keep only new data in the app's own Models.** The
+   session reaches the app's own Models, fields and items (`node(id:)` and the data-engine
+   mutations) and, read-only, the workspace's **goals and timeframes** (`listGoals`, `getGoal`,
+   `listTimeframes`) — those of the workspace and of the Space the app sits in. Everything else in
+   the workspace comes back as an error for now: see [Workspace data](#workspace-data) for which
+   entity is reachable from where. Keep the app's own data in Models rather than in a database of
+   your own: it stays searchable and permissioned in uidu.
    `listModelItems` reads uidu's **search index**, which catches up a moment after a write:
    after `createModelItem` / `deleteModelItem`, update your list from the mutation payload
    instead of re-listing, or the new item is missing. And load models once per app instance
@@ -129,24 +132,39 @@ import { useEffect, useState } from 'react';
 import { UiduAppProvider, useUiduApp } from '@uidu/react';
 import { DEFAULT_HOST_ORIGINS } from '@uidu/app-bridge';
 import {
-  createModelItem, ensureModel, listModelItems, toFieldValuesAttributes,
-  type ModelItem, type UiduClient,
+  createModelItem,
+  ensureModel,
+  listModelItems,
+  toFieldValuesAttributes,
+  type ModelItem,
+  type UiduClient,
 } from '@uidu/client';
 
 export function AppProvider({ children }: { children: React.ReactNode }) {
   // https://*.uidu.org by default; add a local uidu or a custom domain
-  return <UiduAppProvider hostOrigins={[...DEFAULT_HOST_ORIGINS]}>{children}</UiduAppProvider>;
+  return (
+    <UiduAppProvider hostOrigins={[...DEFAULT_HOST_ORIGINS]}>
+      {children}
+    </UiduAppProvider>
+  );
 }
 
 async function loadBookings(client: UiduClient, workspaceAppId: string) {
-  // interim: the app creates its own model on first load (install-time manifest comes later)
+  // interim: the app creates its own model on first load (install-time manifest comes later).
+  // Bookings of a room are data uidu has no place for — hence a Model. Goals, contacts or
+  // people already exist: read them (see Workspace data).
   const model = await ensureModel(client, {
     workspaceAppId,
     name: 'Booking',
     fields: [{ shortname: 'room', name: 'Room', kind: 'string' }],
   });
   await createModelItem(client, {
-    input: { attributes: { modelId: model.id, fieldValuesAttributes: toFieldValuesAttributes(model, { room: 'Blu' }) } },
+    input: {
+      attributes: {
+        modelId: model.id,
+        fieldValuesAttributes: toFieldValuesAttributes(model, { room: 'Blu' }),
+      },
+    },
   });
   return listModelItems(client, { modelId: model.id }); // item.fieldValuesByShortname.room
 }
@@ -156,19 +174,83 @@ export function Bookings() {
   const [items, setItems] = useState<ModelItem[]>([]);
 
   useEffect(() => {
-    if (app.status === 'ready') loadBookings(app.client, app.context.workspaceApp.id).then(setItems);
+    if (app.status === 'ready')
+      loadBookings(app.client, app.context.workspaceApp.id).then(setItems);
   }, [app]);
 
-  if (app.status === 'error') return <p>Open this app from uidu ({app.error.code})</p>; // NOT_EMBEDDED, TIMEOUT…
-  return <ul>{items.map((item) => <li key={item.id}>{item.fieldValuesByShortname?.room}</li>)}</ul>;
+  if (app.status === 'error')
+    return <p>Open this app from uidu ({app.error.code})</p>; // NOT_EMBEDDED, TIMEOUT…
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.fieldValuesByShortname?.room}</li>
+      ))}
+    </ul>
+  );
 }
 ```
 
-`app.context` carries `user`, `space`, `workspaceApp`, `locale` and `theme`. Outside React: `connect()` from
+Field `kind`s for `ensureModel` (and `public/uidu.app.json`): `string` (one line), `text`
+(several lines), `number`, `currency`, `percent`, `date`, `datetime`, `checkbox`, `email`,
+`phone`, `url`, `rating`, `member` (a person of the workspace). `singleSelect` /
+`multipleSelect` need their options created too (`createFieldOption`) — prefer `string` unless
+the choices matter. uidu knows more (`attachments`, `linkedRecord`, `formula`, `progress`,
+`richText`…); leave them out unless the person asks for one.
+
+`app.context` carries `user`, `space`, `workspaceApp`, `locale`, `theme` and `accent` (the page's colour, to set as `--primary`). Outside React: `connect()` from
 `@uidu/app-bridge`, then `createClient(fromBridge(bridge))` from `@uidu/client`. Start a new
 one with `npm create uidu-app@latest my-app -- -t custom-app`: it declares its Models in
 `public/uidu.app.json` and sets `frame-ancestors` so only uidu can frame it.
 
+## Workspace data
+
+**A uidu workspace is not empty.** It already holds the organisation's goals, contacts, deals,
+people, events, courses… An app that asks for "a dashboard of the OKRs behind schedule" or "our
+open deals" is asking about data uidu has — read it. **Create a Model only for data uidu has no
+place for** (the app's own bookings, a checklist, a log). Copying existing records into a Model
+gives the person a second copy that drifts from the real one.
+
+| The workspace's…                    | Functions (`@uidu/client`)                                        | Inside a custom app            |
+| ----------------------------------- | ----------------------------------------------------------------- | ------------------------------ |
+| Goals / OKRs (key results = subgoals) | `listGoals`, `getGoal`, `listTimeframes`; `updateGoal`            | **read** (no `updateGoal`)     |
+| Contacts, organisations             | `listContacts`, `getContact`; `createContact`                     | not yet                        |
+| Deals (CRM)                         | `listDeals`, `getDeal`; `createDeal`, `updateDeal`                | not yet                        |
+| People (employees)                  | `listEmployees`, `getEmployee`, `listOffices`, `listCircles`, `listRoles` | not yet                 |
+| Tasks, notes                        | `updateTask`, `createTask`, `updateNote`, `createNote` (no list)  | not yet                        |
+| Events, courses, bookings, calendars | `listEvents`, `listCourses`, `listBookings`, `listCalendars`, …  | not yet                        |
+| Forms, donations, stories, help center | see [Patterns by Scope](#patterns-by-scope)                    | not yet                        |
+| The app's own Models                | `ensureModel`, `listModelItems`, `createModelItem`, …             | read and write                 |
+
+On a server with an account token (`apiKey`) every row works; "not yet" means a custom app's
+session token is refused for it. **When the data exists in uidu but is not reachable from a custom
+app yet, tell the person** — don't rebuild it in a Model. If the functions you need aren't in the
+table, look for `listX` / `getX` in `@uidu/client` before concluding they don't exist.
+
+### Goals (OKRs)
+
+An objective is a `Goal`; its key results are its `subgoals`; the period it runs over is its
+`timeframe` (`startDate`, `endDate`). `metricKind` is `number`, `percentage`, `currency`,
+`checkbox` or `subgoal` (measured by its key results); `status` is the owner's own judgement:
+`on_track`, `needs_attention`, `off_track`, `accomplished`.
+
+**Values are stored x100.** `initialValue`, `currentValue` and `targetValue` never hold the number
+a person typed, and `progress` is percent x100 (10000 = done). Use the helpers, don't divide by hand:
+
+```ts
+import { listGoals, goalValue, goalProgress, isGoalBehind } from '@uidu/client';
+
+const goals = await listGoals(app.client); // all of them, objectives and key results
+const objectives = goals.filter((g) => !g.parentId);
+const behind = objectives.filter((g) => isGoalBehind(g, { tolerance: 0.1 }));
+
+goalValue(goal, goal.targetValue); // 45 for a 45% target, 1200 for €1,200
+goalProgress(goal);                // 0.45 — done fraction
+```
+
+`isGoalBehind` compares progress with the share of the timeframe already gone (`goalTimeElapsed`);
+show the goal's `status` next to it, it says something different. `updateGoal` takes raw values:
+`toGoalRaw(45)`. A goal's owner, members and activity are not readable from a custom app.
+
 ## Working transparently
 
 The user often can't tell what you're doing when you drive the CLI. Stay legible:
@@ -215,23 +297,66 @@ import { createClient } from '@uidu/client';
 export const uidu = createClient({
   workspace: process.env.UIDU_WORKSPACE ?? '',
   publicToken: process.env.UIDU_PUBLIC_TOKEN, // safe to expose
-  apiKey: process.env.UIDU_API_KEY,           // server-only secret
+  apiKey: process.env.UIDU_API_KEY, // server-only secret
 });
 ```
 
 Required environment:
 
-| Variable | Required | Notes |
-|---|---|---|
-| `UIDU_WORKSPACE` | yes | Your workspace slug (e.g. `acme`) |
-| `UIDU_PUBLIC_TOKEN` | no | Public read-only token, safe to expose |
-| `UIDU_API_KEY` | no | Server-only secret for privileged ops |
+| Variable            | Required | Notes                                  |
+| ------------------- | -------- | -------------------------------------- |
+| `UIDU_WORKSPACE`    | yes      | Your workspace slug (e.g. `acme`)      |
+| `UIDU_PUBLIC_TOKEN` | no       | Public read-only token, safe to expose |
+| `UIDU_API_KEY`      | no       | Server-only secret for privileged ops  |
 
 ## Patterns by Scope
 
-### CMS Pages
+### CMS Sites (new CMS)
 
-CMS pages are made of `pageBlocks`. Fetch a page server-side, pass blocks to `<PageBlocks>` with a component map keyed by the block's `shortname`:
+uidu has two CMS generations. **Sites** are the new one: a `Site` has page types (page-kind Models), pages (ModelItems of a page type) and, on each page, an ordered list of blocks (ModelItems of a block-kind Model). **Projects** (`getPage`/`listPages`, next section) are the legacy CMS — keep using them only for sites already deployed on a Project. Build new sites on Sites. Every read works with a `publicToken`, in RSC and in the browser.
+
+```tsx
+// src/app/[[...slug]]/page.tsx — Server Component
+import { getPageBySlug, getSiteByDomain, type SiteBlock } from '@uidu/client';
+import { notFound } from 'next/navigation';
+import { uidu } from '@/lib/uidu';
+
+const components: Record<string, React.ComponentType<{ block: SiteBlock }>> = {
+  Hero,
+  FAQ,
+};
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const { slug = ['home'] } = await params;
+  const site = await getSiteByDomain(uidu, {
+    domain: process.env.SITE_DOMAIN!,
+  });
+  const page =
+    site &&
+    (await getPageBySlug(uidu, { siteId: site.id, slug: slug.join('/') }));
+  if (!page) notFound();
+  return page.blocks.map((block) => {
+    const Component = components[block.model.name ?? ''];
+    return Component ? <Component key={block.id} block={block} /> : null;
+  });
+}
+```
+
+- `getSiteByDomain(client, { domain })` / `getSite(client, { id })` — the Site (by id in previews, where there is no domain)
+- `getPageBySlug(client, { siteId, slug, includeDrafts? })` → `{ id, slug, model, fields, blocks: [{ id, model, fields, position }] }`, published only by default
+- `listSitePages(client, { siteId, pageType?, includeDrafts? })` — nav/sitemaps; published only, singletons excluded; `pageType` = Model id or name
+- `getSingletonBlock(client, { siteId, shortname })` — header/footer/nav
+- `fields` is already a `{ shortname: value }` map — no `useFields` needed.
+- Block kinds have a `shortname`, but `Model.shortname` isn't exposed by the API yet: key component maps on `block.model.name` for now.
+- Don't call the legacy `listPages`/`getPage` with a Site id — they read Projects only.
+
+### CMS Pages (legacy Projects)
+
+Legacy CMS pages are made of `pageBlocks`. Fetch a page server-side, pass blocks to `<PageBlocks>` with a component map keyed by the block's `shortname`:
 
 ```tsx
 // src/app/page.tsx — Server Component
@@ -249,10 +374,7 @@ export default async function HomePage() {
   if (!page) return <div>Not found</div>;
 
   return (
-    <PageBlocks
-      pageBlocks={page.pageBlocks}
-      components={{ Hero, Feature }}
-    />
+    <PageBlocks pageBlocks={page.pageBlocks} components={{ Hero, Feature }} />
   );
 }
 ```
@@ -296,19 +418,19 @@ const event = await getEvent(uidu, { id });
 
 Event fields:
 
-| Field | Notes |
-|---|---|
-| `event.id` | |
-| `event.name` | Display name |
-| `event.body` | WYSIWYG doc — render with `<RichText>` |
-| `event.cover` | Image URL (string) or null |
-| `event.description` | Plain string summary |
-| `event.instance.beginsAt` | ISO datetime of start |
-| `event.instance.finishesAt` | ISO datetime of end |
-| `event.instance.id` | Instance identifier |
-| `event.primaryAddress` | Location data |
-| `event.currentCapacity` | Numeric capacity |
-| `event.isPaidEvent` | Boolean |
+| Field                       | Notes                                  |
+| --------------------------- | -------------------------------------- |
+| `event.id`                  |                                        |
+| `event.name`                | Display name                           |
+| `event.body`                | WYSIWYG doc — render with `<RichText>` |
+| `event.cover`               | Image URL (string) or null             |
+| `event.description`         | Plain string summary                   |
+| `event.instance.beginsAt`   | ISO datetime of start                  |
+| `event.instance.finishesAt` | ISO datetime of end                    |
+| `event.instance.id`         | Instance identifier                    |
+| `event.primaryAddress`      | Location data                          |
+| `event.currentCapacity`     | Numeric capacity                       |
+| `event.isPaidEvent`         | Boolean                                |
 
 ### Stories (Blog)
 
@@ -395,10 +517,12 @@ later throws. `FieldValueAttributes` exposes no `value` key — `content` is the
 
 ```ts
 // ✅ Correct — every answer wrapped
-fieldValuesAttributes: [{ fieldId: 'f1', content: { value: 'hello@example.com' } }]
+fieldValuesAttributes: [
+  { fieldId: 'f1', content: { value: 'hello@example.com' } },
+];
 
 // ❌ Wrong — silently loses the answer
-fieldValuesAttributes: [{ fieldId: 'f1', content: 'hello@example.com' }]
+fieldValuesAttributes: [{ fieldId: 'f1', content: 'hello@example.com' }];
 ```
 
 It holds for **every** field kind, not just strings — `{ value: 42 }`, `{ value: true }`,
@@ -465,7 +589,9 @@ All `body` fields on Event, Story, DonationCampaign, etc. are structured documen
 ```tsx
 import { RichText } from '@uidu/react';
 
-{story.body != null && <RichText doc={story.body} />}
+{
+  story.body != null && <RichText doc={story.body} />;
+}
 ```
 
 The prop is `doc`, not `children`. The component handles paragraphs, headings, lists, links, and inline marks.
@@ -517,12 +643,12 @@ Or pick a template directly:
 npm create uidu-app@latest my-app -- -t events
 ```
 
-| Template | What it builds |
-|---|---|
-| `minimal` | CMS landing page with `PageBlocks` + Hero/Feature blocks |
-| `events` | Event listing + `/event/[id]` detail |
-| `stories` | Blog listing + `/story/[id]` detail (magazine layout) |
-| `donations` | Campaigns listing + `/campaign/[id]` detail with progress bars |
+| Template     | What it builds                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------ |
+| `minimal`    | CMS landing page with `PageBlocks` + Hero/Feature blocks                                         |
+| `events`     | Event listing + `/event/[id]` detail                                                             |
+| `stories`    | Blog listing + `/story/[id]` detail (magazine layout)                                            |
+| `donations`  | Campaigns listing + `/campaign/[id]` detail with progress bars                                   |
 | `custom-app` | An app inside a uidu Space: `<UiduAppProvider>`, data in its own Models (`public/uidu.app.json`) |
 
 Every template ships with Next.js 16 App Router, Tailwind v4 and an `.env.example` (the CLI

package/skills/uidu-design/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: uidu-design
+description: Use when building or restyling the UI of an app that runs inside uidu (a custom app framed in a Space or workspace, including one made in the uidu app builder) — layout, components, colours, typography, empty and loading states. Makes the app look like the uidu page around it instead of a patch sewn on.
+license: MIT
+metadata:
+  author: uidu
+  version: '0.1.0'
+---
+
+# Looking like uidu
+
+A custom app is an iframe in the middle of a uidu page. Above it sits uidu's header, with
+the app's name and its buttons; around it, uidu's sidebar. Whatever the app draws has those
+on every side, so the only good outcome is an app that reads as one more uidu page.
+
+That is mostly already done for you. The template ships **uidu's own tokens**
+(`src/app/globals.css`) and **uidu's own components** (`src/components/ui/`), generated from
+uidu's source. The rules below are about not undoing it.
+
+## 1. Use the kit, don't restyle it
+
+- Build from `src/components/ui/*`: `Button`, `Input`, `Field`, `Select`, `Checkbox`,
+  `Switch`, `Textarea`, `Table`, `Tabs`, `Dialog`, `Sheet`, `DropdownMenu`, `Popover`,
+  `Tooltip`, `Badge`, `Alert`, `Empty`, `Skeleton`, `Spinner`, `Item`, `Card`, `Calendar`,
+  `Toaster` (`toast()` from `sonner`)…
+- A `<button>`, `<input>`, `<table>` or `<select>` written by hand is almost always a
+  component you didn't import. A `<div className="rounded-lg border p-4">` is a `Card`, a
+  coloured pill is a `Badge`, a status line is an `Alert`.
+- Don't edit the files in `src/components/ui/`: they are regenerated from uidu. Compose them,
+  and pass `className` for layout (margins, width, flex), not for colour or size.
+- Need one that isn't there? `npx shadcn add @uidu/<name>` works where the network allows it
+  (not in the builder's sandbox). Otherwise build it from the ones you have.
+
+## 2. Colours are tokens, never a palette
+
+Only the semantic classes, which flip with uidu's light/dark theme:
+
+| For                                                | Use                                                           |
+| -------------------------------------------------- | ------------------------------------------------------------- |
+| page, text                                         | `bg-background`, `text-foreground`                            |
+| secondary text, captions, labels                   | `text-muted-foreground`                                       |
+| panels, popovers                                   | `bg-card`, `bg-popover` (usually via `Card`, `Popover`)       |
+| hover, selected row                                | `bg-accent`, `hover:bg-accent`                                |
+| subtle fill (a weekend, a disabled row)            | `bg-muted`                                                    |
+| the app's accent (main button, active item, links) | `bg-primary`, `text-primary`                                  |
+| error, destructive action                          | `text-destructive`, `bg-destructive/10`                       |
+| done / needs attention / neutral info              | `text-success`, `text-warning`, `text-info` (and `/10` fills) |
+| lines                                              | `border` (already the right colour), `divide-y`               |
+| charts                                             | `bg-chart-1` … `bg-chart-5`, `var(--chart-1)`                 |
+
+Never `text-gray-*`, `bg-white`, `text-black`, `bg-blue-500`, `text-red-600`, a hex value or
+an inline `style={{ color }}`: they don't follow the theme, and in dark mode they break.
+`--primary` is the page's accent: uidu sends it (`context.accent`, set by
+`app-provider.tsx`), so it changes with the workspace and the app. Don't set it yourself,
+and don't add a brand colour of your own — `bg-primary` already is one.
+
+## 3. Typography: uidu's density
+
+- Body text is `text-sm` (14px): paragraphs, table cells, list items, form fields.
+- `text-base` only for emphasis: the figure a card is about, a record's name.
+- `text-xs` is rare: counters, hints.
+- Headings inside the app are `text-sm font-semibold` (a section) or `text-base
+font-semibold` at most. No `text-2xl` hero titles: this is a tool, not a landing page.
+- A label never outweighs its value: label `text-sm text-muted-foreground`, value
+  `font-medium`.
+- The font is Inter, set in `layout.tsx`. Don't load another one.
+
+## 4. Layout: fill the frame, don't frame it again
+
+- **No title that repeats the app's name.** uidu's header already shows it. If the page needs
+  a bar, make it a toolbar: `flex h-14 shrink-0 items-center justify-between gap-2 border-b
+px-4` with context (a count, a filter, a period) on the left and actions on the right.
+- **No second navigation shell**: no sidebar, no top nav, no footer, no logo. For a few views
+  use `Tabs` in the toolbar; for a detail, a `Sheet` or a `Dialog`.
+- **Edge to edge.** The page fills the iframe (`flex min-h-screen flex-col`): no centred
+  `max-w-2xl` column with a card floating in it, no outer margin. Content is inset `px-4`
+  (16px), the same as uidu's header above, so their left edges line up.
+- Sections are separated by `border-b`, not by stacking cards with gaps. Use `Card` for a
+  real sub-surface (one card per related thing), never a card inside a card.
+- **No dead space.** When the data is short, the empty area is filled by an `Empty` state
+  (it grows with `flex-1`) or the page ends where the data ends. Never leave the bottom
+  third of the frame blank.
+- Spacing on Tailwind's scale (`gap-2`, `gap-3`, `p-4`, `px-4`); no `px-[13px]`.
+
+## 5. Data
+
+- Rows of things are a `Table` (`TableHeader`/`TableHead`/`TableBody`/`TableRow`/`TableCell`),
+  with `pl-4` on the first column and `pr-4` on the last, to align with the toolbar.
+- A table that scrolls keeps its header visible: bound the table's own container with
+  `containerClassName="h-full overflow-y-auto"` and make the `TableHead`s `sticky top-0
+bg-background`. Wrapping the table in your own scroller does not work.
+- Dates and numbers through `Intl` with `context.locale` (`toLocaleString(locale)`,
+  `Intl.NumberFormat(locale, …)`), never hand-formatted.
+- A thing that spans several days or columns is **one** element across them, not one per cell.
+
+## 6. States
+
+Every screen has four, and each has a shape:
+
+| State                | Shape                                                                                                       |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| connecting / loading | `Skeleton`s shaped like the content (rows, a card) — not a centred spinner, not "Loading…" text alone       |
+| empty                | `Empty` with an icon (`EmptyMedia variant="icon"`), a title, one sentence and, if there is one, the action  |
+| error                | `Alert variant="destructive"` near what failed, with what to do; a failed write keeps what the person typed |
+| saving               | the button stays, disabled, with a `Spinner` inside; `toast()` for a result that lands elsewhere            |
+
+## 7. Icons
+
+- `lucide-react` only, imported by name: `import { Plus } from 'lucide-react'`.
+- Inside a component (`Button`, `DropdownMenuItem`, `Badge`, `Alert`, `EmptyMedia`…) write
+  `<Plus />` with **no** `size-*` class: the component sizes it. Elsewhere `size-4`.
+- Never change `strokeWidth`. Colour with `text-*` tokens.
+- An icon-only button is `variant="ghost" size="icon"` with an `aria-label`, and the icon
+  `aria-hidden="true"`.
+
+## 8. Accessible by default
+
+- Every field has a label (`Field` + `FieldLabel htmlFor`), every icon-only button an
+  `aria-label`.
+- Actions are buttons, navigation is links; nothing clickable is a `<div onClick>`.
+- Messages that appear after an action (`Alert`, a saved state) are announced: `role="alert"`
+  for errors, `aria-live="polite"` for the rest.
+- Motion stays small (the components' own); spatial animations get `motion-safe:`.
+
+## 9. Words
+
+- Short, plain, in the person's language (`context.locale`); sentence case ("New booking",
+  not "New Booking").
+- Say what happened and what to do next, not an error code.
+
+## Before you finish
+
+Run `npm run check`: it type-checks and flags raw palette colours, hex values, hand-written
+`<button>`/`<input>`/`<table>`, other icon sets and `strokeWidth`. Fix what it reports.
+Then look at the page in dark mode too: if something is invisible or glaring there, it is
+using a colour instead of a token.

package/skills/uidu-design/metadata.json

@@ -0,0 +1,8 @@
+{
+  "name": "uidu-design",
+  "version": "0.1.0",
+  "author": "uidu",
+  "license": "MIT",
+  "homepage": "https://developers.uidu.org",
+  "repository": "https://github.com/uidu-org/api.js/tree/main/packages/skills/skills/uidu-design"
+}