Make documentation standalone and generalize examples
This commit is contained in:
Melvin Strobl
@@ -0,0 +1,198 @@
|
||||
# Fluksio design guidelines
|
||||
|
||||
UI reference for the app, its dashboard editor and documentation site.
|
||||
Paths below are relative to this repository.
|
||||
|
||||
## Design language
|
||||
|
||||
Use neutral white and near-black surfaces with a slate-blue primary accent.
|
||||
Reserve terracotta for one secondary action per view. `--card` is the main
|
||||
surface. Separate surfaces with borders and elevation. Controls are pills;
|
||||
cards and panels use a 16px radius.
|
||||
|
||||
## Colour tokens
|
||||
|
||||
| Token | Light | Dark | Use |
|
||||
|---|---|---|---|
|
||||
| `--background` | `#ffffff` | `#0a0a0a` | page |
|
||||
| `--foreground` | `#333232` | `#f5f5f5` | body text |
|
||||
| `--card` / `--popover` | `#ffffff` | `#1a1a1a` | dominant surface; dark lifts above the page |
|
||||
| `--card-foreground` / `--popover-foreground` | `#333232` | `#f5f5f5` | text on those surfaces |
|
||||
| `--primary` | `#4a7189` | `#7ba3b8` | primary fills, active state, focus ring |
|
||||
| `--primary-foreground` | `#ffffff` | `#0a0a0a` | text on `--primary` |
|
||||
| `--primary-nested` | `#152128` | `#345160` | a reading drawn inside a `--primary` fill |
|
||||
| `--brand-secondary` | `#de8f6e` | `#e5a184` | the one secondary call-to-action per view |
|
||||
| `--brand-secondary-foreground` | `#333232` | `#0a0a0a` | text on `--brand-secondary` |
|
||||
| `--secondary` / `--muted` | `#f2f2f2` | `#232323` | recessed surfaces |
|
||||
| `--secondary-foreground` | `#333232` | `#f5f5f5` | text on those |
|
||||
| `--muted-foreground` | `#6b6b6b` | `#a3a3a3` | secondary text, section headers |
|
||||
| `--accent` | `#f5f5f5` | `#262626` | hover / selected surface |
|
||||
| `--accent-foreground` | `#333232` | `#f5f5f5` | text on `--accent` |
|
||||
| `--destructive` | `#b94d4d` | `#cf6666` | destructive actions, failing nodes |
|
||||
| `--status-success` | `#5e8b6d` | `#87b596` | a node's last run succeeded |
|
||||
| `--status-warning` | `#b45309` | `#e8a33d` | a node that works, but degraded, such as a device that is offline |
|
||||
| `--chart-1` … `--chart-8` | see [Chart palette](#chart-palette) | | chart series, in slot order |
|
||||
| `--border` / `--input` | `#e4e4e4` | `#2a2a2a` | hairlines, field borders |
|
||||
| `--ring` | `#4a7189` | `#7ba3b8` | focus ring; always equals `--primary` |
|
||||
| `--sidebar*` | mirrors card / accent / primary | | sidebar surface set |
|
||||
|
||||
The identity blue `#59849b` stays in the wordmark. Use `--primary` for controls
|
||||
so text on primary fills meets contrast requirements. `--primary-nested` is
|
||||
for stacked readings inside a primary fill, separated by a gutter.
|
||||
|
||||
- Use tokens in UI components. Custom SVG glyphs may use `currentColor`.
|
||||
- Keep `--sidebar-accent` equal to `--accent`.
|
||||
- Use one `--brand-secondary` action per view.
|
||||
- Name every status in text. Running uses `--primary`, success
|
||||
`--status-success`, failure `--destructive`, and degraded
|
||||
`--status-warning`. Idle has no indicator.
|
||||
- Home's brain graph uses primary discs as its identity. Its outer ring uses
|
||||
`--foreground` for runnable nodes and terracotta for flow faults. Failed
|
||||
nodes keep a terracotta disc until acknowledged. Persistent faults keep
|
||||
their labels visible.
|
||||
|
||||
### Chart palette
|
||||
|
||||
| Slot | Hue | Light | Dark |
|
||||
|---|---|---|---|
|
||||
| 1 | `--primary` | `#4a7189` | `#7ba3b8` |
|
||||
| 2 | orange | `#e26f00` | `#d26600` |
|
||||
| 3 | violet | `#6f49ca` | `#8d71e6` |
|
||||
| 4 | green | `#00721b` | `#55c15e` |
|
||||
| 5 | orchid | `#c66ae1` | `#dd8bf6` |
|
||||
| 6 | ochre | `#966a00` | `#ae7c00` |
|
||||
| 7 | teal | `#00a093` | `#00c0b1` |
|
||||
| 8 | magenta | `#b32474` | `#bf4483` |
|
||||
|
||||
Take colours in slot order. Line charts stop at five series and show a legend
|
||||
when there is more than one. Reserve red, sage green and amber for status.
|
||||
The terminal UI uses the terminal's named ANSI colours instead.
|
||||
|
||||
## The dashboard is exempt
|
||||
|
||||
User-defined dashboards can choose `fluksio`, `material` or `glass` under
|
||||
`frontend/src/components/Dashboard/ui/`. The default `fluksio` look follows
|
||||
these guidelines. Other looks may change surfaces and motion.
|
||||
|
||||
Behavior, keyboard handling and accessibility stay in `ui/core/`.
|
||||
A dashboard palette overrides tokens on its own canvas, with colours assigned
|
||||
by position. It must preserve contrast, named status, 44px touch targets and
|
||||
reduced-motion behavior. Fault and success colours keep their meanings.
|
||||
Widgets use container queries to follow their tile size.
|
||||
|
||||
Dashboard motion presets live in `ui/core/motion.ts`; the app shell uses
|
||||
`frontend/src/lib/motion.ts`.
|
||||
|
||||
## Typography
|
||||
|
||||
Use the self-hosted Inter variable font at
|
||||
`frontend/public/fonts/inter-latin-variable.woff2` for body text, headings and
|
||||
wordmarks. `.font-display` selects it for display text. Use the system
|
||||
monospace stack through `font-mono` for code, message names and payloads.
|
||||
|
||||
Use Tailwind's size scale. Arbitrary `text-[…]` sizes are banned and checked
|
||||
by the `no-arbitrary-font-size` hook.
|
||||
|
||||
Section headers use:
|
||||
|
||||
```text
|
||||
text-xs font-medium uppercase tracking-[0.5px] text-muted-foreground
|
||||
```
|
||||
|
||||
## Radius
|
||||
|
||||
| Utility | Value | Use |
|
||||
|---|---|---|
|
||||
| `rounded-full` | pill | buttons, inputs, toggles, chips, badges |
|
||||
| `rounded-sm` | 8px | checkboxes, small chips, nested items |
|
||||
| `rounded-md` | 12px | menus, popovers, tooltips, textareas |
|
||||
| `rounded-lg` | 16px | cards, panels, dialogs, alerts, sidebar |
|
||||
| `rounded-xl` | 28px | large containers |
|
||||
|
||||
## Elevation
|
||||
|
||||
Use `shadow-e1` for resting cards, `shadow-e2` for floating surfaces, and
|
||||
`shadow-e3` for modals. Avoid arbitrary or stock shadow utilities on surfaces.
|
||||
Borders use `border border-border`, or `border-input` on fields.
|
||||
|
||||
## Motion
|
||||
|
||||
Use the `motion` package with presets from `frontend/src/lib/motion.ts`.
|
||||
Keep JavaScript timings aligned with the CSS easing and duration tokens.
|
||||
|
||||
- Easing is `emphasized` for entering or expressive movement, `standard` for
|
||||
neutral transitions.
|
||||
- Durations are 150, 200 and 300 ms. One-shot activity feedback uses 500 ms.
|
||||
- Variants are `fadeIn`, `scaleIn`, `slideUp`, `overlayFade` and `listStagger`.
|
||||
- Wrap the app in `<MotionConfig reducedMotion="user">`.
|
||||
|
||||
## Microcopy
|
||||
|
||||
Keep captions short. Put explanations in `InfoTip`, `PanelSection.help` or
|
||||
`FieldLabel.help`. A tooltip holds one or two sentences; longer instructions
|
||||
belong in the docs. Help must work by tap as well as hover.
|
||||
|
||||
Visible supporting text describes state, such as an empty list, a stopped
|
||||
flow or an error. A page may have one descriptive line below its heading.
|
||||
Say what a control does. Keep design rationale in repository documentation.
|
||||
|
||||
Avoid em dashes in UI strings. Empty-value placeholders and structural
|
||||
separators are allowed. The `no-em-dash` hook checks these rules, with
|
||||
separators listed in `frontend/scripts/no-em-dash.allow.json`.
|
||||
|
||||
## Iconography
|
||||
|
||||
Use Lucide. Custom glyphs belong in `frontend/src/components/icons/` as 24×24
|
||||
SVGs with no fill, `currentColor` strokes, weight 2 and round caps.
|
||||
|
||||
## Shells
|
||||
|
||||
The authenticated app uses a `bg-card` region with a floating translucent
|
||||
sidebar. The flow editor floats its controls over the node canvas. Both use
|
||||
`bg-card/80 backdrop-blur-md`, a token border and `shadow-e2`.
|
||||
|
||||
## Responsive
|
||||
|
||||
Use `md` at 768px as the mobile boundary. Keep `useIsMobile()` and Tailwind's
|
||||
`md:` usage aligned, with stock breakpoints.
|
||||
|
||||
1. Keep the page within the viewport. Give wide tables and charts their own
|
||||
`overflow-x-auto` region. Use `min-w-0` on flex and grid children when
|
||||
content could stretch the page. `frontend/tests/mobile.spec.ts` checks this.
|
||||
2. Cap floating controls with `max-w-[calc(100vw-2rem)]` and allow wrapping.
|
||||
3. Use 44px touch targets below `md`, 32px above. Use `icon-touch`, `sm-touch`
|
||||
or matching responsive utilities.
|
||||
4. Turn floating panels into full-screen sheets on phones with the shared
|
||||
`Flow/SidePanel`. Gate canvas side insets behind `md:`.
|
||||
5. Provide tap or visible alternatives to hover actions.
|
||||
6. Keep dragging, placing and resizing on desktop. Flow layout is automatic,
|
||||
left-to-right on desktop and top-to-bottom on phones. Rectangular dashboard
|
||||
grids stack to one column on phones.
|
||||
|
||||
Use `grid gap-* sm:grid-cols-2 lg:grid-cols-N` for card grids and
|
||||
`p-4 sm:p-6 md:p-8` for page gutters.
|
||||
|
||||
## Overlay surfaces & content chips
|
||||
|
||||
Floating surfaces use `bg-card/80 backdrop-blur-md`, a token border and
|
||||
`shadow-e2`. Use token alpha for translucency; panel opacity also fades text.
|
||||
|
||||
Content chips are transparent at rest and fill on hover or selection.
|
||||
Use `hover:bg-accent/50` where hover and selection need distinct states.
|
||||
Segmented controls use one bordered pill with no dividers, transparent
|
||||
segments and `bg-accent` for the selected segment.
|
||||
|
||||
## UI configuration
|
||||
|
||||
`frontend/components.json` uses shadcn style `new-york`, CSS variables and
|
||||
Lucide icons. Components under `frontend/src/components/ui/` are owned by
|
||||
this repository. Update token definitions, component usage and this reference
|
||||
together when changing the design.
|
||||
|
||||
## UX
|
||||
|
||||
- Keep common actions easy to reach without context menus.
|
||||
- Apply theme through the `.dark` class on `<html>` and the pre-paint theme
|
||||
script so the first frame uses the chosen theme.
|
||||
- A dashboard subtree can use `.theme-light` or `.theme-dark` independently.
|
||||
Menus and tooltips rendered outside it must carry that theme class too.
|
||||
Reference in New Issue
Block a user