roz-ui
Skill10 starsChanged 29 days agoApache-2.0View on GitHub
Use for any UI work in the Roz for LSC Electron app (src-renderer/ — chat, Settings, Library, Studio screens, CSS). The app's design conventions, the shared UI primitives, and how to screenshot the running app to check a change before calling it done.
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- lsc-account-managementSkill
- lsc-activity-planSkill
- lsc-agentforceSkill
- lsc-app-alertsSkill
- lsc-briefingsSkill
- lsc-calendar-tot-routineSkill
- lsc-config-migrationSkill
- lsc-consent-managementSkill
- lsc-custom-scriptsSkill
- lsc-data-migrationSkill
- lsc-data-modelSkill
- lsc-db-schemaSkill
- lsc-demo-data-loadingSkill
- lsc-events-managementSkill
- lsc-field-emailSkill
- lsc-health-checkSkill
- lsc-home-page-configurationSkill
- lsc-implementation-reviewSkill
- lsc-implementationSkill
- lsc-integration-patternsSkill
- lsc-intelligent-contentSkill
- lsc-key-account-managementSkill
- lsc-lists-filtersSkill
- lsc-mobile-app-settingsSkill
- lsc-mobile-validationSkill
- lsc-next-bestSkill
- lsc-performance-validationSkill
- lsc-product-managementSkill
- lsc-provider-engagement-complianceSkill
- lsc-quick-actions-configurationSkill
- lsc-reporting-analyticsSkill
- lsc-sample-managementSkill
- lsc-surveysSkill
- lsc-territory-alignmentSkill
- lsc-troubleshootSkill
- lsc-user-managementSkill
- lsc-visit-managementSkill
- salesforce-querySkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 1 is distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 33
No accent stripes: No coloured left or top border (or inset box-shadow) on cards, rows, callouts or blockquotes.
- Very specific: line 37
Use Lucide (lucide-react) only, at 14px in buttons and 16px in rows, with aria-hidden when there's a label beside it.
- Very specific: line 39
Don't hand-draw <svg> icons.
- Distinctive: line 40
Don't use characters as icons (✓ ✗ × ▾ ↻ ●).
- Very specific: line 45
Every colour token has a light value in the @media (prefers-color-scheme: light) block (the test checks).
- Very specific: line 58
Every pane's top bar is --toolbar-height (52px), and is a drag region (-webkit-app-region: drag, with no-drag on its controls), aligned …
- Very specific: line 73
Copy: use sentence case and plain words.
- Very specific: line 74
Accessibility: every icon-only control needs an aria-label, and every field a label.
- Very specific: line 75
Use aria-current / aria-selected for the current item.
- Very specific: line 81
Run npx vitest run test/unit/ui-conventions.test.ts.
- Very specific: line 83
Run npm run electron:build, then node scripts/ui-shots.mjs tour /tmp/roz-shots.
- Very specific: line 87
Add ROZ_SHOTS_THEME=light (or dark) to take the tour in one palette.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Roz UI conventions
Roz should feel like one native Mac app. Every screen is built from the same few primitives,
sizes and tokens. test/unit/ui-conventions.test.ts enforces the mechanical rules. The rest is
judgement: check it by looking at the app (see Verify below).
Exempt: the simulated iPad (.studio-ipad-screen, Ipad*.tsx, screens/, assets/, and the iPad
CSS listed in the test's IPAD list). It reproduces LSC Mobile's iOS look and follows
lifesciences-ios, not these rules.
Use the primitives (src-renderer/components/ui/)
| Need | Use |
| Loading / empty / error state of a pane | <StateView kind="loading|empty|error" title detail icon actions layout="fill|inline" /> |
| Pass / fail / warning at a glance | <StatusIcon tone="pass|error|warning|info|unknown|skipped" />, or a .ui-pill <tone> label |
| Busy indicator | <Spinner size={…} /> — the only spinner |
| Tabs or a mode switch | <Segmented> — never hand-rolled tab buttons |
| Buttons | .studio-btn (+ primary, ghost, danger, sm, lg); icon-only: .ui-icon-btn with an aria-label |
| Fields | .ui-field / .studio-input / .studio-select, labelled with .ui-label; checkbox + label: .ui-check |
| Section heading with a count | .ui-section-title with a .count span: "ORG-WIDE · 6 of 8 passing", never run together |
| View appearing | ui-enter on the pane, keyed by view so it fades in on change |
Need something new? Add it to components/ui/ and ui.css so the next screen can reuse it.
Rules
- No accent stripes. No coloured left or top border (or inset box-shadow) on cards, rows,
callouts or blockquotes. Show tone with a
StatusIcon, a pill, or a tinted background (--*-subtle) with a hairline border. - Icons:
- Use Lucide (
lucide-react) only, at 14px in buttons and 16px in rows, witharia-hiddenwhen there's a label beside it. - Don't hand-draw
<svg>icons. Data charts are the only exception (CHART_SVGin the test). - Don't use characters as icons (✓ ✗ × ▾ ↻ ●).
- Lucide v1 names:
TriangleAlert,CircleAlert,CircleQuestionMark(the old aliases don't exist).
- Use Lucide (
- Tokens, not literals (
:rootinstyles.css):- Colour:
--text-*,--bg-*,--fill-*,--border*,--accent,--success|error|warning(-subtle). Hex andrgba()only define a token. The one allowed literal is#fff, for text on the accent. Every colour token has a light value in the@media (prefers-color-scheme: light)block (the test checks); a new token needs both. Tint a tone withcolor-mix(in srgb, var(--tone) 12%, transparent). - Appearance (System / Light / Dark, in Settings) sets Electron's
nativeTheme.themeSource(src-electron/theme.ts); CSS followsprefers-color-scheme. Code that can't usevar()readscssToken()and re-renders onuseColorScheme()(src-renderer/theme.ts; Mermaid inmermaid.ts). - Type:
--font-2xs(badges only),--font-xs11,--font-sm12,--font-base13 (app chrome),--font-md14 (reading),--font-lg,--font-xl,--font-2xl(page titles),--font-display,--font-code. No rawpxfont sizes. - Space: the 4pt grid,
--space-1to--space-10. - Radius:
--radius,--radius-sm,--radius-xs. - Motion:
--transition-fast,--ease-out.
- Colour:
- Sizes:
- Controls are
--control-sm24,--control28 or--control-lg32px tall. - Every pane's top bar is
--toolbar-height(52px), and is a drag region (-webkit-app-region: drag, withno-dragon its controls), aligned with the traffic lights. - Rows in lists and rails are 30px. Long labels end in "…" (
text-overflow: ellipsis) and don't wrap.
- Controls are
- Every async view has all three states: loading (
StateView kind="loading"or a skeleton, never a blank pane), empty (what it is and what to do, with an icon and usually an action), and error (the message, plus Retry). - Words and colour agree. A verdict that says "Works, with 5 issues" is amber, not red with a
green bar. Map tone with
verdictTone()(studio/readiness.ts) rather than ad hoc. - Headers survive a narrow window:
- Titles keep a readable minimum width (
flex: 1 1 280px; min-width: 0). - Actions wrap below the title, or collapse to icons (
.collapsible+ container query instudio.css). - Nothing overflows sideways.
- Titles keep a readable minimum width (
- Dialogs and sheets:
- Escape closes them and so does a backdrop click; they pop in with
ui-pop-in. - The primary button is on the right of the footer.
- Escape closes them and so does a backdrop click; they pop in with
- Copy: use sentence case and plain words. Subtitles fit on one line (ellipsis +
titlefor the full text). - Accessibility: every icon-only control needs an
aria-label, and every field a label. Usearia-current/aria-selectedfor the current item.
Verify — look at it
Type-checking doesn't show a wrapped header, a mismatched colour or a squashed button. After a UI change:
- Run
npx vitest run test/unit/ui-conventions.test.ts. If it fails, fix the code; only widen the test's exemptions for genuine iPad simulation or charts. - Run
npm run electron:build, thennode scripts/ui-shots.mjs tour /tmp/roz-shots. It launches the app with its saved connection and org, visits every main screen (chat, Library, Commands, Settings, Studio Overview / Check a user / What changed / Sync health / a rep's sync detail / Test plans / First sync / a feature's Readiness and board / iPad preview, plus a narrow 960×640 window), and saves PNGs. It also prints renderer console errors. AddROZ_SHOTS_THEME=light(ordark) to take the tour in one palette; otherwise it follows the OS. - Read the screenshots for every screen you touched, in both palettes, including the narrow one. Check alignment, wrapping, truncation, spacing, state coverage and colour, against the rules above.
- To check one state or interaction, use the REPL:
printf 'nav .studio-rail-item::Sync health\nwait 3000\nss sync\nquit\n' | node scripts/ui-shots.mjs repl /tmp/roz-shots. It also takesclick TEXT,eval JS,size W Handerrors.
It needs playwright-core (a devDependency) and drives Electron directly, so no browser download is
needed. A dev instance (npm run electron:dev) can keep running alongside it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

