@uidu/skills 0.4.0 → 0.5.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.5.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

@@ -164,7 +164,7 @@ export function Bookings() {
 }
 ```
 
-`app.context` carries `user`, `space`, `workspaceApp`, `locale` and `theme`. Outside React: `connect()` from
+`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.

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"
+}