Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/docs/design-system.md
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
design-system.md · 13.4 KB · 263 lines

The Design System

DBBASIC's design system is not a component library you depend on — it is a semantic contract with a thin, themeable renderer, delivered as an object. It has three layers, and only the top one is pixels.

flowchart TD
    SEM["Layer 1 — Semantics<br/>schema: types, enum, relation,<br/>list_mode, transitions, permissions"] --> REND
    TOK["Layer 2 — Tokens<br/>semantic roles: surface, text,<br/>accent, positive/warning/danger"] --> REND
    REND["Layer 3 — Renderers<br/>web pages · Scroll · shell · AI"]
    TOK -.theme = a set of role values.-> THEMES["Themes as data:<br/>base · paper · terminal · yours"]

The governing idea: define once, project everywhere, own no copies

Everything below is one principle seen from different angles. State the design once — as tokens, as a shared stylesheet object, as a nav object, as a schema — and let every surface project it. No page owns a copy of the theme; it references /style. No page owns a copy of the nav; it includes /nav. No app hardcodes a widget; it declares a field's meaning. Because nothing downstream owns a copy, changing the source changes the whole product at once, with nothing to chase.

This is why rebranding the entire twelve-app suite and giving it a shared navigation bar was two objects edited live — no deploy, no migration, no per-page rework. If a future change to the look or the chrome ever requires editing many pages, that is the signal that a copy leaked in and should be pulled back into a shared object. Guard this property; it is the whole value.

Layer 1 — Semantics (the source of truth)

Design decisions live in the schema, not in markup. A field that declares enum means "one of these values"; each surface picks its own control (dropdown on the web, segmented control in Scroll, a spoken list to the AI). views.list_mode picks table / cards / feed. transitions says which state moves are legal. Permissions decide which controls exist at all. See schema forms and permissions.

We deliberately do not use a widget-prescriptive ui_schema. The predecessor (q9) paired each schema with a React-JSON-Schema-Form ui_schema that said things like "ui:widget": "radio". That only ever renders on one surface — a radio hint is meaningless to an AI, the shell, a voice interface, or a native app. Semantics render everywhere; widget instructions render once. This is the single most important choice in the system, and the reason a design here can span surfaces that do not exist yet.

Permissions are affordances. A control exists because the caller can perform the action, not because markup drew it and then hid it. A delete button appears when the policy allows delete; a project filter appears because there is a project_id relation; a column appears because list_fields lists it. The design system renders capability — which is why an AI acting for a user, or a shared component, can never show a control the user could not actually use.

Layer 2 — Tokens (roles, not colors)

The visual vocabulary is a small set of semantic roles — surface (bg, panel, line), text (text, muted), accent, and status (positive, warning, danger) — plus spacing, radii, shadow, and two type families. Components are written against the roles, never against raw colors, so a retheme changes values in one place and nothing in any page moves.

Layer 3 — Renderers, and the design system as an object

The stylesheet is itself a DBBASIC object: site_style, served at /style. Every page links to it (<link rel="stylesheet" href="/style">) instead of carrying its own CSS. Because it is an object, the whole visual system is versioned, rollback-able, and live-editable like everything else — retheming is one reversible object change, not a deploy.

Other renderers consume the same two layers: Scroll's generated Flutter forms and lists, the shell's terminal, and the AI (whose "UI" is the schema's label/help text — good microcopy is design work that serves the form, the accessibility label, and the AI tool description at once).

The app shell — chrome contributed, not copied

Navigation is part of the design system, and it follows the same rule. The site_nav object, served at /nav, injects one shared top bar into every page that includes <script src="/nav"></script>: brand, an app switcher across installed apps, global search (⌘K / Ctrl-K) over /api/search, an Ask-AI link to the shell, a notification bell reading the notifications collection, and a user menu (appearance, sign out). Its styling lives in /style, so it themes with everything else.

The point is that a package (app-theme) contributes this bar to every other app without those apps knowing — a thing a Django app could never do to its siblings. Adding a nav item is one edit to one object; every app gets it. If you find yourself pasting nav markup into a page, stop: add it to site_nav.

The bell is live: it subscribes to the notifications collection over the /ws websocket and updates the instant something happens, with a 20s poll as backup. Every app page is live the same way — each subscribes to its collection and auto-refreshes (150ms debounced) when a record it can see changes, over the one shared socket, via window.dbbasicSubscribe(collection, handler). Add a live list to a new page in one line. Auto-update on events is the thing the old dashboard/Channels stacks never did cleanly — see the realtime contract.

Themes are data — and packages

A theme is just a set of values for the token roles. site_style ships three built in:

  • base — the DBBASIC identity: a warm dark (per the earth-theme rule

"warm, not cold blue-black") with a terracotta/ember accent, carried forward from the palette q9 already established.

  • paper — a warm light theme.
  • terminal — high-contrast green-on-black.

The active theme lives in the object's state. There is a visual chooser at /appearance (the site_appearance object): it reads the available themes and their preview swatches from /style?info=true and lets an admin click one to reskin the whole instance; non-admins see the active theme read-only. Or switch over HTTP:

POST /style   {"theme": "terminal"}          # admin session only
POST /style   {"tokens": {"accent": "#5aa7ff"}}   # custom role overrides
GET  /style?info=true                          # {active, available, previews, tokens}

site_style self-gates writes to admin sessions (using the unspoofable injected identity), so a public execute grant can serve the CSS to everyone while only operators change the look.

A theme is a package. Installing a package that ships its own site_style (or that sets custom tokens) reskins the whole instance — design distributed the same way apps are. A community can publish themes; you install the one you like; you can fork it because it is one small, readable object. Per-user theming (each account choosing a theme) is a planned extension built on the same roles plus the shell_preferences pattern.

Forms, tables, search, and filters

The base stylesheet carries a genuinely complete component vocabulary so generated UIs and hand-written pages share one look: form fields with labels/help/required markers and validation states; tables with sortable headers, hover, numeric alignment, and pagination; a toolbar with a search input and filter chips; buttons as intents (primary / neutral / danger) rather than colors; badges; and first-class empty / loading / denied / error states.

That is the visual layer. The generative renderer that reads a schema and emits these — the successor to q9's django_tables2 + django_filters (which worked because they were declarative from a single source) unified across table, cards, and feed with search and filters wired to search.fields — is the next build. q9's honest lesson is that this substrate must be one renderer, not the four disconnected implementations it grew (django_tables2 for tables, two incompatible form engines, hand-written cards and feeds). The semantics and the token vocabulary are now in place for it.

Building a page against the design system

<link rel="stylesheet" href="/style">
...
<div class="wrap">
  <header class="app"><h1>Notes</h1><div class="who">…</div></header>
  <div class="toolbar">
    <input class="search grow" placeholder="Search…">
    <div class="filters"><button class="chip" aria-pressed="true">All</button></div>
  </div>
  <div class="cards">…</div>
</div>

No inline CSS, no framework, no build step — just the shared classes. When the instance's theme changes, this page changes with it. Page-unique layout (a form's column grid, an edit-mode toggle) may stay in a small <style> block, but it must use the token variables (var(--panel), var(--line), var(--accent)) — never hardcoded colors — so it reskins too.

Why this is a design system, not a style guide

The test that separates the two: change the source, and does the whole product change with no copies to chase? Here it does — edit /style, every page reskins; edit /nav, every page's chrome updates; edit a schema, every surface re-renders that field. A folder of CSS classes and a component catalog is a style guide; you still hand-apply it and it drifts. A design system propagates from one place. Protect that difference: the day a change stops propagating is the day it quietly became a style guide.

Why not a dashboard template

The web-template industry (Bootstrap admin themes, and the marketplaces that sell them — q9 itself shipped on the "Volt" dashboard) assumed everything is a dashboard: a fixed chrome of sidebar, topbar, cards, and a data table, into which you pour your app. That is widgets-before- meaning — the shape is the product, and the only app you can express is the one the widgets already draw. It is the same mistake as a widget-prescriptive ui_schema, at the scale of a whole product. It is also why q9 accumulated 110 KB of override CSS fighting its template: when the chrome is copied into every page, changing it means fighting it everywhere.

Reading modes (table / cards / feed) are the direct rejection of the one-shape assumption: a note is read individually (cards), a task is compared to others (table), a message is sequential (feed). The dashboard world only had the table.

The reason no one built it this way earlier is not taste, it is arithmetic. Projecting one schema into a web form, a table, a Flutter widget, an AI tool description, and an accessibility label meant hand-writing five renderers per app — insane in 2015, so buying the frozen template was rational. What changed is that the schema is now legible to a model, a model can render a surface, and the runtime hot-loads it with no deploy — so the marginal cost of a surface collapsed, and the correct architecture (declare meaning once, project everywhere) finally pays. Build for that, not for the dashboard era.

Current edges (honest)

  • Theme-complete, component-incomplete. The token/theme/app-shell

layers are done and propagate. The component vocabulary exists in /style, but pages still assemble it by hand — the generative renderer (schema → dense list with row actions, filters, and relative timestamps) is not built yet. It is the next big design build, and it needs a created_at field added to schemas first (nothing captures creation time today, so there are no relative timestamps to show).

  • Web + tokens today. Scroll shares the token roles but the web and

Flutter renderers are not unified against one contract yet.

  • Instance-level theming. Per-user theme choice is a planned extension

on the same roles plus shell_preferences.

  • The shell page (/shell) deliberately keeps its own terminal palette

and does not link /style or /nav — a focused full-screen mode. The admin dashboard is not yet on the shared shell either.

Extending it correctly — rules for future builds

When adding to the design system, keep the propagation property intact:

  1. Contribute, don't copy. New chrome goes in a shared object

(site_style, site_nav), never pasted into pages. If it must live in a page, it is page-unique and must use tokens.

  1. Tokens are roles, never hex. Add a role (e.g. --info) if you need

a new meaning; never a raw color in a component or a page.

  1. Semantics, not widgets. Express new capability as schema meaning

(a new field key, a new views mode) that every surface can interpret — resist any per-surface "render as X" instruction; that is ui_schema returning, and it collapses you back to one surface.

  1. Let permissions draw the controls. Show an action because the

policy allows it, not because you wrote the button.

  1. One renderer per concern. When the generative renderer lands, route

all lists/forms through it — do not grow a second form engine. q9 grew four; that fragmentation is the failure mode to avoid.

  1. No framework to fight. Do not adopt a CSS framework you will then

override. The system is small and authoritative on purpose.

  1. If a change stops propagating, fix the leak — pull the copy back

into the shared object — rather than editing many pages.

Follow these and the next person (or the next model, or a stranger who forks this) can retheme, re-chrome, or extend the whole product from a handful of objects — which is the point.