UI Craftsmanship
Sjel is a workstation that one person reads many times a day. A good view answers the reader's
question at a glance, keeps every other action one step away, and never makes the reader wait.
The rules below are written in terms of intent, not a framework. They apply to the GPUI app on
the Mac and the iPhone and to the public site in website/. For GPUI implementation details, use
the gpui skill.
Source for rules 1–3: Kole Jain, "The 3 dashboard UI flaws that give away you've never built
one" (https://www.youtube.com/watch?v=Ksx9C2-3yMo), adapted to Sjel. Rule 4 and the tip rule
come from the projects record Sjel/Connected shell.md (2026-10-06).
Rule 1: the data picks the form
Before you choose a layout, name the shape of the data. Then use the form that shape asks for.
| The data is |
Show it as |
Not as |
| A value from a fixed set (status, category, kind) |
A chip with a tone |
Free text in a column |
| A number, an amount, a date, a count |
Right-aligned, monospace, tabular figures |
Left-aligned proportional text |
| Long free text in a dense row |
One line, truncated, full text in a tip or the detail |
A row that wraps to three lines |
| A row the reader cannot act on (cancelled, spent, zero) |
Dimmed, still in place |
Hidden, or styled like the live rows |
| Records ordered by time |
A timeline or a list grouped by day |
A table sorted by a timestamp column |
| Many records with the same fields |
A table, with a board or timeline view of the same set |
A grid of cards |
| One record with many fields |
A property list in a side panel |
A wide table with one row |
| A total that changes over time |
A small chart next to the list it summarizes |
Only the list |
Colour comes from the data. A tone says what a value means (settled, needs a decision, broken,
chosen, not active). Decorative colour is a defect. One urgent item in red reads instantly; ten
coloured items read as noise.
Rule 2: the explicitness ladder
Every action has a place on a ladder from most to least visible. Put each action on the lowest
rung that its use still allows.
| Rung |
Form |
Use for |
| 1 |
Labelled control, always visible |
The one primary action of the view |
| 2 |
Icon control, always visible, with a tip |
Frequent actions where space is tight |
| 3 |
Shown on hover and on keyboard focus |
Secondary per-row actions (remove, copy, open externally) |
| 4 |
Inside a popover, menu or side panel |
Rare actions and editors (share, change a price, history) |
| 5 |
Keyboard shortcut or command palette only |
Power actions that already have a visible path elsewhere |
Rules for placing an action:
- Rank by frequency first, then by cost of a mistake. A destructive action never sits on
rung 1 or 2 next to the primary action.
- A new feature goes into a side panel or popover on the page that owns its data. Give it a
page of its own only when it has its own dataset and its own primary action.
- Rung 3 must work without a mouse. An action that shows on hover also shows on focus, and is
always visible on a device with no hover.
- Hiding is sequencing, not deleting. A disclosed detail stays in the accessibility tree.
- Lower rungs cost less to render. Content on rung 4 renders when it opens, not with the page.
Rule 3: the state inventory
Most of a finished interface is the UI the reader does not see at first. Before a component is
done, check each state below. Write "not applicable" for a state only when you know why.
| State |
Requirement |
| Hover |
Rows and controls that react to a click show that they react |
| Focus |
Every control is reachable by keyboard and shows a visible focus ring |
| Tip |
Every icon-only control and every ambiguous label has a tip. The tip is also its accessible name. A tip never carries the only reason for something: the reason is also one click away |
| Empty |
Say nothing when quiet is normal. Say what to do next when the reader expected data |
| Loading |
Only for remote data. Reserve the final size so nothing shifts when data arrives |
| Error |
Say what failed and offer retry where retry can work |
| Stale |
Data older than its refresh interval shows its age |
| Disabled |
A disabled control says why in its tip |
| Inactive |
Spent or cancelled records are dimmed, not removed |
| Overflow |
Long text truncates, and the full text is one hover or one click away |
Rule 4: show the join
Sjel's value is the joins between its areas: the trip that explains the spend, the event that
explains the trip. Every view of one record lists what it touches in other capabilities, and
opens it in place (the inspector, website/content/capabilities/links.md). In review, a record view that lists
nothing outside its own capability gets a question.
Rule 5: one product, native surfaces
A Mac app and a future iPhone app should feel like Sjel, not like scaled copies of each other.
- Keep shared concepts, names, semantic roles and task intent consistent. Adapt navigation, density, input and layout to each platform.
- Use platform capabilities when they make a Sjel task more direct. Explain access requests when they appear, and keep a useful path when a capability is unavailable.
- Treat external interfaces as inspiration, not specifications. Reuse useful principles only when they serve Sjel; use Sjel's own design tokens and actual workflows.
- Keep visual principles here. Route toolkit-specific implementation and verified platform support to the relevant implementation skill.
Speed budget
Speed is a feature of the design, not a later optimisation.
- A click or keypress shows a visible response in under 100 ms. Local data shows with no
spinner.
- Every primary action has a keyboard path. Lists move with J/K and open with Enter.
- Motion animates only transform and opacity, and stays at or below the motion tokens
(100–300 ms). Respect reduced motion.
- Prefer a native platform feature to a script: a native popover, a
<dialog>, a <details>.
In GPUI, prefer the framework's own element.
- Do not render what the reader cannot see (rule 2, item 5). Long lists render in pages or
virtualize.
Workflow
- Name the view's question. A view answers one question ("what needs me today", "where did
the money go"). The answer goes first. Everything else moves down the ladder.
- Shape the data with rule 1. Use a kit primitive. Add a primitive to the kit only when a
page needs one that does not exist.
- Place every action with rule 2.
- Walk the state inventory with rule 3, list the joins with rule 4, and apply rule 5
when the workflow spans platforms.
- Check the tells and the budget. Read
references/anti-slop-tells.md and
references/mechanical-sympathy-in-ui.md.
- Run surface-specific checks. For GPUI, the app's tests and
bench-scroll; for the site,
website/build. For toolkit details, route to the relevant implementation skill.
Reference routing
| Topic |
Reference |
| The AI design tells, their code signatures and fixes |
references/anti-slop-tells.md |
| Typography, number alignment, spacing, density, semantic colour |
references/visual-hierarchy-and-typography.md |
| Zero layout shift, compositor-only motion, contrast, reduced motion |
references/mechanical-sympathy-in-ui.md |
| Rust desktop implementation and verified platform limits |
Use the gpui skill; keep version-specific GPUI guidance there. |
1---2name: ui-craftsmanship3description: Guides design, layout, styling and visual review of Sjel interfaces across web and native clients. Covers data-shaped layouts, progressive disclosure, complete UI states, cross-capability joins, coherent cross-device experiences, speed, anti-vibe-coding tells and mechanical sympathy. Use when designing or reviewing a page, table, panel or component, when planning a shared Mac and iPhone experience, or when auditing an interface for generic AI or SaaS design tells. Do not use for backend Rust APIs, non-visual scripts, prose writing or version-specific GPUI implementation; use gpui for the latter.4allowed-tools: Read, Write, Edit, Bash5metadata:6 source: https://skillmd.com/skills/larsboes/ui-craftsmanship7---89# UI Craftsmanship1011Sjel is a workstation that one person reads many times a day. A good view answers the reader's12question at a glance, keeps every other action one step away, and never makes the reader wait.1314The rules below are written in terms of intent, not a framework. They apply to the GPUI app on15the Mac and the iPhone and to the public site in `website/`. For GPUI implementation details, use16the `gpui` skill.1718Source for rules 1–3: Kole Jain, "The 3 dashboard UI flaws that give away you've never built19one" (https://www.youtube.com/watch?v=Ksx9C2-3yMo), adapted to Sjel. Rule 4 and the tip rule20come from the projects record `Sjel/Connected shell.md` (2026-10-06).2122## Rule 1: the data picks the form2324Before you choose a layout, name the shape of the data. Then use the form that shape asks for.2526| The data is | Show it as | Not as |27|---|---|---|28| A value from a fixed set (status, category, kind) | A chip with a tone | Free text in a column |29| A number, an amount, a date, a count | Right-aligned, monospace, tabular figures | Left-aligned proportional text |30| Long free text in a dense row | One line, truncated, full text in a tip or the detail | A row that wraps to three lines |31| A row the reader cannot act on (cancelled, spent, zero) | Dimmed, still in place | Hidden, or styled like the live rows |32| Records ordered by time | A timeline or a list grouped by day | A table sorted by a timestamp column |33| Many records with the same fields | A table, with a board or timeline view of the same set | A grid of cards |34| One record with many fields | A property list in a side panel | A wide table with one row |35| A total that changes over time | A small chart next to the list it summarizes | Only the list |3637Colour comes from the data. A tone says what a value means (settled, needs a decision, broken,38chosen, not active). Decorative colour is a defect. One urgent item in red reads instantly; ten39coloured items read as noise.4041## Rule 2: the explicitness ladder4243Every action has a place on a ladder from most to least visible. Put each action on the lowest44rung that its use still allows.4546| Rung | Form | Use for |47|---|---|---|48| 1 | Labelled control, always visible | The one primary action of the view |49| 2 | Icon control, always visible, with a tip | Frequent actions where space is tight |50| 3 | Shown on hover and on keyboard focus | Secondary per-row actions (remove, copy, open externally) |51| 4 | Inside a popover, menu or side panel | Rare actions and editors (share, change a price, history) |52| 5 | Keyboard shortcut or command palette only | Power actions that already have a visible path elsewhere |5354Rules for placing an action:55561. Rank by frequency first, then by cost of a mistake. A destructive action never sits on57 rung 1 or 2 next to the primary action.582. A new feature goes into a side panel or popover on the page that owns its data. Give it a59 page of its own only when it has its own dataset and its own primary action.603. Rung 3 must work without a mouse. An action that shows on hover also shows on focus, and is61 always visible on a device with no hover.624. Hiding is sequencing, not deleting. A disclosed detail stays in the accessibility tree.635. Lower rungs cost less to render. Content on rung 4 renders when it opens, not with the page.6465## Rule 3: the state inventory6667Most of a finished interface is the UI the reader does not see at first. Before a component is68done, check each state below. Write "not applicable" for a state only when you know why.6970| State | Requirement |71|---|---|72| Hover | Rows and controls that react to a click show that they react |73| Focus | Every control is reachable by keyboard and shows a visible focus ring |74| Tip | Every icon-only control and every ambiguous label has a tip. The tip is also its accessible name. A tip never carries the only reason for something: the reason is also one click away |75| Empty | Say nothing when quiet is normal. Say what to do next when the reader expected data |76| Loading | Only for remote data. Reserve the final size so nothing shifts when data arrives |77| Error | Say what failed and offer retry where retry can work |78| Stale | Data older than its refresh interval shows its age |79| Disabled | A disabled control says why in its tip |80| Inactive | Spent or cancelled records are dimmed, not removed |81| Overflow | Long text truncates, and the full text is one hover or one click away |8283## Rule 4: show the join8485Sjel's value is the joins between its areas: the trip that explains the spend, the event that86explains the trip. Every view of one record lists what it touches in other capabilities, and87opens it in place (the inspector, `website/content/capabilities/links.md`). In review, a record view that lists88nothing outside its own capability gets a question.8990## Rule 5: one product, native surfaces9192A Mac app and a future iPhone app should feel like Sjel, not like scaled copies of each other.9394- Keep shared concepts, names, semantic roles and task intent consistent. Adapt navigation, density, input and layout to each platform.95- Use platform capabilities when they make a Sjel task more direct. Explain access requests when they appear, and keep a useful path when a capability is unavailable.96- Treat external interfaces as inspiration, not specifications. Reuse useful principles only when they serve Sjel; use Sjel's own design tokens and actual workflows.97- Keep visual principles here. Route toolkit-specific implementation and verified platform support to the relevant implementation skill.9899## Speed budget100101Speed is a feature of the design, not a later optimisation.102103- A click or keypress shows a visible response in under 100 ms. Local data shows with no104 spinner.105- Every primary action has a keyboard path. Lists move with J/K and open with Enter.106- Motion animates only transform and opacity, and stays at or below the motion tokens107 (100–300 ms). Respect reduced motion.108- Prefer a native platform feature to a script: a native popover, a `<dialog>`, a `<details>`.109 In GPUI, prefer the framework's own element.110- Do not render what the reader cannot see (rule 2, item 5). Long lists render in pages or111 virtualize.112113## Workflow1141151. **Name the view's question.** A view answers one question ("what needs me today", "where did116 the money go"). The answer goes first. Everything else moves down the ladder.1172. **Shape the data** with rule 1. Use a kit primitive. Add a primitive to the kit only when a118 page needs one that does not exist.1193. **Place every action** with rule 2.1204. **Walk the state inventory** with rule 3, list the joins with rule 4, and apply rule 5121 when the workflow spans platforms.1225. **Check the tells and the budget.** Read123 [`references/anti-slop-tells.md`](references/anti-slop-tells.md) and124 [`references/mechanical-sympathy-in-ui.md`](references/mechanical-sympathy-in-ui.md).1256. **Run surface-specific checks.** For GPUI, the app's tests and `bench-scroll`; for the site,126 `website/build`. For toolkit details, route to the relevant implementation skill.127128## Reference routing129130| Topic | Reference |131|---|---|132| The AI design tells, their code signatures and fixes | [`references/anti-slop-tells.md`](references/anti-slop-tells.md) |133| Typography, number alignment, spacing, density, semantic colour | [`references/visual-hierarchy-and-typography.md`](references/visual-hierarchy-and-typography.md) |134| Zero layout shift, compositor-only motion, contrast, reduced motion | [`references/mechanical-sympathy-in-ui.md`](references/mechanical-sympathy-in-ui.md) |135| Rust desktop implementation and verified platform limits | Use the `gpui` skill; keep version-specific GPUI guidance there. |