diff --git a/docs/design/brief.md b/docs/design/brief.md index fb5f2e7..eba9288 100644 --- a/docs/design/brief.md +++ b/docs/design/brief.md @@ -53,10 +53,18 @@ The owner's reference is Microchip's MPLAB Code Configurator (MCC), its device r - Every change still goes through the core into `board.yaml` and `system.yaml`, shown as a diff before anything is written (specification §5, §6). -**From MCC, still to bring in** (its Pin Manager and Pins view): per-pin *start high*, analog, direction, weak -pull-up, open-drain and interrupt-on-change; and its **pin grid**, functions in rows and pins in columns, each cell a -lock that is free, taken or locked. The first draft's pin and peripheral options are too few: the next round widens -both (owner, 2026-11-12). +**Widened on 2026-11-12, after the owner's feedback on the first draft:** + +- **Pin manager:** every I/O pin with its mode (input, output, analog, alternate), pull, output type, speed, start + level and interrupt edge, each active only where the mode allows it; filters for pins in use, free pins and all + 50; board-wired pins (the LED, the button, the ST-LINK) fixed by the board description. +- **Pin grid,** as in MCC: functions down, the 50 I/O pins across grouped by port, each cell free, assigned, in + conflict, or fixed and locked. A click moves a function to another pin that can carry it; for the ADC it picks + channels. +- **Peripheral forms in sections** (basic, advanced, interrupts and DMA, driver): flow control, filters, triggers, + prescalers, the DMA stream and channel each request uses, interrupt priorities, the EmbLinkRTOS driver class, the + device name and the devices on a bus. Checks such as an ADC clock above 36 MHz, or a button pull-down fighting the + board's pull-up. ## 3a. Configuring the RTOS @@ -84,6 +92,24 @@ both (owner, 2026-11-12). threads at one priority, a timer period that is not a whole number of ticks, no debug descriptor. - In the Debug stage the same graph comes alive: threads light up as they run, queues fill and drain. +## 3b. Every board, every chip + +EmbLink Studio supports every board EmbLinkRTOS describes: 12 boards of 7 families today, from an 8-bit AVR to +simulated boards with no pins. **No screen is designed for one chip.** The mockups show the NUCLEO-F446RE only as an +example; every screen draws from the board's resolved model (`hw.json`), as the specification requires (§4, §6). + +| What changes per chip | How the screens adapt | +| --- | --- | +| The package (`lqfp64`, `lqfp144`, `qfn60`, `pdip28`, none) | The chip is drawn from it: four sides for QFP and QFN (QFN with its pad), two rows for DIP, a ball grid for BGA. A simulated board (MPS2, QEMU) shows its memory map and peripherals instead | +| How a pin gets its function: an AF number per pin (STM32), a function slot per GPIO (RP2350), or fixed by the peripheral (AVR) | The pin grid shows `AF7`, `F3`, or a fixed cell that cannot be chosen. Conflicts and moves work the same way for all three | +| The peripherals and what they offer (DMA, PIO, FPU, MPU) | The catalogue is the chip's; forms show only the sections the chip has, so no DMA section on an ATmega | +| The clock tree | Every readout (baud error, SCL, ADC rate) is computed by the core from the chip's clocks, never in the GUI | +| What the kernel supports on the chip | The Kernel page follows the port's `Kconfig` defaults and limits: `tiny` on AVR, reboot on fault, no debug descriptor | + +A board is chosen when a project is created (the Start screen), and the board pill in the toolbar shows and changes +it for an open project. A board the views do not cover fully still opens: what they cannot show is listed read-only +with its source (specification §1). + ## 4. A complete debugger Everything a professional embedded developer expects, plus what only an RTOS-aware tool can show: @@ -98,6 +124,180 @@ Everything a professional embedded developer expects, plus what only an RTOS-awa | RTOS | Threads and their states, objects, stacks and high-water marks, the timeline | | Trouble | Fault analyzer, crash-record decoding, SWO/ITM console and trace | +**First draft, 2026-11-12** (artboard "Direction B + C · Debug"), halted at a breakpoint on the NUCLEO-F446RE: + +- the controls in the toolbar (continue, pause, step over, into, out, by instruction, reset, stop) and a status pill + that says why the target stopped: a breakpoint, a step, a watchpoint, a pause; +- the RTOS threads from the debug descriptor, each with its state and stack high-water mark, and the call stack of + the selected one, from its live registers or from the context the kernel saved; +- breakpoints and watchpoints, with the hardware they use (Cortex-M4: 6 FPB comparators, 4 DWT comparators); +- the source with the Thumb-2 disassembly interleaved, the current line and instruction, values shown inline; +- variables: locals, a watch list, and live expressions read over SWD while the target runs; +- core and FPU registers, the ones the last step changed in amber; peripheral registers decoded from the SVD, with + their fields, writable while halted; +- a bottom panel: the console (UART, ITM over SWO, GDB), the RTOS timeline from the trace ring, the kernel objects + live, and the last crash record decoded, linked back to Configure › RTOS; +- a **memory viewer** as an editor tab, like VS Code's hex editor: go to an address or a symbol, the chip's regions + (from the board) and a clickable map of the build's sections and thread stacks, a 16-byte grid as bytes, 16-bit, + 32-bit or float values with ASCII, symbols coloured in place, changed bytes marked, a data inspector that decodes a + pointer to the symbol it points at, writes while halted, and a warning where a read has side effects. + +**Code text uses VS Code's metrics on macOS:** a 12 px monospace font on 18 px lines (owner, 2026-11-12). + +## 4a. The code editor + +First draft, 2026-11-12 (artboard "Direction B + C · Code"). The best of the editors people like, plus what only an +RTOS-aware editor can show: + +| From | What | +| --- | --- | +| VS Code | tabs, breadcrumbs, the minimap with problem marks, peek definition, Problems, Terminal, split editor, its line metrics | +| CLion | inlay hints with parameter names, code lenses above functions, quick fixes | +| Xcode | issues shown at the end of their line, each with its fixes | +| Sublime | one box to go to anything: files, symbols, pins, threads, settings, commands | +| GitLens | change bars in the gutter, blame on the current line | + +Only EmbLink Studio: + +- **Lenses with RTOS facts:** the thread a function runs as, its priority, stack and last high-water mark, its flash + size from the build; an interrupt handler's IRQ, class and priority. +- **Hardware names explained:** `pin_led`, `dev_bme280`, `log_q` or `EXTI15_10_IRQn` open a card with the pin, the bus, + the queue or the IRQ they stand for, where they are defined, and their state on the last run. +- **RTOS checks with fixes:** a blocking call in an interrupt handler (an error, with "use EMB_NO_WAIT"); a call chain + deeper than its thread's stack, from `-fstack-usage` (with "raise the stack in system.yaml"). +- **Completion that knows contexts:** each function says whether it is safe in an interrupt. +- **Generated code read-only,** with a banner pointing to Configure; renaming a generated name sends you to its source. + +### Every part is a panel (owner, 2026-11-12) + +As in VS Code, and further: Explorer, Outline, Source Control, Commits, Problems, Build, Terminal, Serial and +Extensions are each a panel of their own, with their own scroll. Any panel can be dragged by its title, or moved from +its menu, to the left or right side bar, the panel area below, the editor area as a tab, or a floating window. Side +bars stack panels and fold them; the panel area shows them as tabs and can be maximized. The editor splits into +groups, and tabs move between them. Splitters resize everything. Layouts can be saved, with presets (Default, Focus, +Review, Terminal), per project (§3, specification §6). + +**Polish, 2026-11-12 (owner: "elegant, still pro").** Every area is a card with rounded corners on a darker ground, +6 px apart. Panel titles in normal case, actions that brighten on hover, a slim indicator in the activity bar, and a +quiet status bar. Panels, tabs and floating windows are moved by dragging, with docking guides as in Visual Studio: +release on a guide to dock (left, right, panel area, editor tab, split), anywhere else to float. The Explorer has +type icons, folders that fold, indent guides, git colours on names and folders, ignored and generated folders +marked, and a filter. + +### Extensions, Git first + +Features that not every user needs are **extensions**, as in VS Code, so they can be turned off: Git, the language +server, the serial monitor, the trace timeline, the EmbSIM runner. **Git** is built in: stage, unstage, commit with +the DCO sign-off on by default, push, branches, the commit graph, diffs in the editor, change bars and blame. Turning +an extension off removes its panels and its decorations in the editor. + +## 4b. Start + +First draft, 2026-11-12 (artboard "Direction B + C · Start"): + +- **The welcome window:** the app's mark and version, four actions (new project, open, clone from Git, run an + example), the board **connected now** (its probe found on USB) with "new project for this board", recent + projects with their board and last build, and the examples EmbLinkRTOS ships. +- **New project in three steps,** each one shown in a stepper that keeps the choices made: + 1. **Board:** every board EmbLinkRTOS describes, filtered (connected, hardware, simulated) and searched, each + drawn from its package and marked connected, draft (not yet curated), simulated, or not available yet (an + ESP32 whose SoC is not described). + 2. **Template:** empty, blinky, console shell, sensor and logger, SPI device. A template that needs hardware the + board does not describe is shown with what is missing ("this board has no LED the RTOS can drive"). + 3. **Details:** name, location, the EmbLinkRTOS release pinned, the profile from the board's defaults, the + toolchain found or downloaded, git with a signed-off first commit, build right away. +- **Creating** shows each step as the core runs it: the manifests, the pinned RTOS, generation, CMake, git, the + first build and its sizes. Then: open in Configure or Code, or flash and run. +- **A cloned project opens untrusted** (specification §9): its files are shown, nothing in it runs until trusted. + +**Second draft (owner, 2026-11-12: "good ideas, implementation far below the other screens").** Rebuilt to the +standard of Code: each board drawn as it looks (the NUCLEO's white board with its ST-LINK part and blinking LD2, the +Pico 2 W's slim green board, the Uno's teal board, the micro:bit's LED matrix, the ESP32 modules, simulated boards as +blueprints); the connected board as the hero of the welcome window; recent projects grouped by date with their board; +new project as a sheet over the window, with a vendor sidebar, template cards that preview their threads and queues, +a System Settings form beside a live `emb-project.yaml`, and creation shown on the board, whose LED lights when done. + +## 4c. Verify + +First draft, 2026-11-12 (artboard "Direction B + C · Verify"). Verify is where a project gets its evidence, under the +rules EmbLinkRTOS already keeps (`docs/engineering/timing-and-evidence.md`, the support matrix, the HIL records). The +screen never claims more than the evidence supports. + +- **Run on** the board (through its probe) or its emulator (EmbSIM, QEMU), in the checked or release build. **Run + suite** flashes each test image, checks that the flashed image is the one built (`image_sha256` against + `flashed_sha256`), and streams results in as they arrive. +- **Two suites:** EmbLinkRTOS on this board (for the NUCLEO-F446RE: 41 images, 254 cases, grouped as kernel, + interrupts and the port, devices and drivers, faults and crash records, benchmarks) and the project's own tests. +- **Each image** shows its cases with the real outcomes: passed, failed, expected failure, skipped with a reason, + disabled, not run. A failed case shows its message and **Debug this case**, which opens Debug on that image, + stopped where it failed. +- **The support tier** of the board (1 hardware, 2 emulated, 3 described), from the generated matrix, never declared + by the board; the history of archived runs; the other boards in the matrix. +- **Console, Run record and Benchmarks** below: the `hil:` console, the `emb-hil-archive v1` record (board, preset, + build, configuration, git commit, port, flash command, hashes), and benchmarks against FreeRTOS built the same way. +- **What this evidence supports:** each claim marked as supported, qualified or not supported, with its basis. A + benchmark is a measured mean, not a maximum and not a bound; an emulator run is functional evidence only + (SIM-003); worst-case latency needs an established bound before it can be claimed. +- **Archive as evidence** is offered only for a hardware run where everything passed. It files the records + (`tools/hil/archive.py`) and shows the entry added to `hardware-runs.json`. A failing or partial run is kept, + never archived as support. + +## 4d. One frame for every screen + +The polish pass, 2026-11-12. Configure (Hardware, RTOS, Kernel), Code, Debug, Start and Verify now share one frame: + +- **The title bar:** the window controls, the project, the four stages as one segmented control (each a link to + its screen), then what belongs to the stage: the board and Generate and Build on Configure, the debug controls and + the halt state on Debug, the run target on Verify. +- **Cards on a dark ground:** each panel is a rounded card (12 px) on a near-black ground, 6 px apart, as in Code. + Inside a card, groups are a faint fill with hairline separators, the way System Settings groups its rows. +- **The same controls everywhere:** segmented controls, switches with a shadowed knob, status dots, a toast at the + bottom, and one palette for state (cyan for the selection and actions, green passed, amber warning, red error). +- **Configure › Hardware** gains a finer chip, peripheral cards with a colour edge, a legend that selects, a + floating zoom control, peripherals listed with their own tiles, and memory shown as capacity bars. The behaviour + is unchanged: live readouts, conflicts and the fix, the pin manager and the pin grid. +- **Configure › Kernel** moves its search and the Hardware | RTOS | Kernel switch into the header of its centre card. +- **Debug** splits threads, the call stack and breakpoints into cards, puts the editor and the panel in two cards, + and uses segmented tabs for the inspector. + +## 4e. Signature moments + +Owner, 2026-11-12: build all five (artboard "Signature moments"). Motion everywhere lasts 200 to 400 ms, eases +out, and starts where the cause is. + +1. **Hello, board** (Start). Plugging in a board names it and draws it as it looks, before anything is asked. + Identity comes from the probe and the chip's ID code, never a guess. The drawing shows the real board: LD2 in it + follows GPIOA ODR read over SWD. The greeting ends in one next step, "New project for this board". +2. **One click from conflict to fixed** (Configure › Hardware). The conflict glows on the pin and the fix sits + beside it, offered only when valid. The route leaves PA5 and draws itself to PB3; amber turns green only when the + generator accepts the board. +3. **Priority is a place** (Configure › RTOS). Dragging a thread snaps it to real levels (never 0, the idle + level). The ceiling follows its highest user, and checks appear while dragging, each citing its rule. +4. **From a crash to the fix** (Debug, Configure › RTOS, Run). The crash record survives the reset. Every claim + comes from it (CFSR, BFAR, the stack at the fault). The fix links to the exact field, prefilled, never applied + silently, and the next run shows the new high-water mark. +5. **The hardware seal** (Verify). The seal appears only when every test passed on the board and the run is + archived, never from emulation or a partial run. It names the board, the date and the record behind it, and the + matrix is regenerated from the archive. + +Every pin on the chip in Configure › Hardware now carries its name, and clicking a pin or its name opens its row +in the pin table. + +## 4f. Design tokens, languages and Settings + +The visual language is written down as tokens in [`tokens.json`](tokens.json) (artboard "Design tokens", built from +the same file): colour, type, space, radius, size, elevation and motion. The Qt frame reads them; nothing else +defines a colour, a size, a timing or how text is laid out. + +**Three languages (owner, 2026-11-12):** English (the source), French and Simplified Chinese. Chinese text uses +PingFang SC on macOS and a bundled Noto Sans SC on Windows and Linux, after Inter; it breaks between characters and +is never set below 12 px, so the 11 px caption becomes 12 px without capitals. No layout is mirrored. Every visible string comes from a Qt translation file, layouts leave room for text 35% longer than +English, and labels never get a fixed width. Option keys, register, pin and file names, spec references and code are +never translated. Numbers and dates follow the chosen language; hex values never do. + +**Settings is built directly in Qt (owner, 2026-11-12),** from these tokens, without a mockup. The language is one of +its first settings, applied without a restart. + ## 4g. How you move around Artboard "How you move around", 2026-11-12. @@ -133,16 +333,18 @@ walk the selection history; with nothing selected it shows the project. specification chose Widgets for the frame (§11 q2), and the docking library (Qt Advanced Docking System) is Widgets-only. Before deciding, build the same small screen both ways and compare. 2. **Light appearance.** Dark is designed first; a light appearance, as macOS offers, follows the same tokens. -3. **The other screens:** Start, Code, Debug, Verify. +3. **The other screens:** every screen has a draft in the common frame (§4d); the signature moments are drafted (§4e). 4. **Drawing a connection:** dragging from a thread to an object to say who uses it. +5. **The word for IDE plug-ins.** "Module" already means a firmware code package (EmbLinkRTOS-parts, specification §5, + §8). The mockups say **extension** for IDE plug-ins such as Git, to keep the two apart; the owner decides. ## 6. How the design proceeds One step at a time, each decision written here before anything is built: 1. The feeling (§1): done. -2. The signature moments: the 3 to 5 interactions people remember. +2. The signature moments: drafted, five (§4e). 3. How you move around: stages, the command palette, the inspector, the keyboard: drafted (§4g). -4. The visual language, as design tokens (colour, type, spacing, radii, motion) that Qt uses everywhere. +4. The visual language, as design tokens (colour, type, spacing, radii, motion) that Qt uses everywhere: drafted (§4f). 5. The screens, each mocked up and iterated: Configure › Hardware and Configure › RTOS (first drafts done; the layout is liked, the options need widening), then Start, Code, Debug, Verify. diff --git a/docs/design/tokens.json b/docs/design/tokens.json new file mode 100644 index 0000000..d1cbb73 --- /dev/null +++ b/docs/design/tokens.json @@ -0,0 +1,506 @@ +{ + "name": "EmbLink Studio · dark", + "version": 1, + "about": "Design tokens for EmbLink Studio, taken from the mockups in docs/design/brief.md. The Qt frame reads these; nothing else defines a colour, a size, a timing or how text is laid out. Colours are sRGB hex, or rgba() for translucent layers drawn over the ground.", + "color": { + "surface": { + "ground": { + "value": "#111214", + "use": "The window behind every card" + }, + "titlebar": { + "value": "#17181b", + "use": "The title bar" + }, + "card": { + "value": "#1b1c20", + "use": "Side panels, the inspector, the bottom panel" + }, + "work": { + "value": "#18191d", + "use": "The centre card: editor, chip canvas, the run" + }, + "canvas": { + "value": "#15161a", + "use": "Canvases, under a dot grid" + }, + "deep": { + "value": "#111214", + "use": "Code, diffs and records inside a card" + }, + "floating": { + "value": "rgba(40,42,47,.97)", + "use": "Toasts, menus, the command palette" + } + }, + "fill": { + "group": { + "value": "rgba(255,255,255,.035)", + "use": "A group of settings rows inside a card" + }, + "well": { + "value": "rgba(0,0,0,.35)", + "use": "Segmented-control tracks, search fields, inputs" + }, + "readout": { + "value": "rgba(0,0,0,.25)", + "use": "Computed values and their tiles" + }, + "control": { + "value": "rgba(255,255,255,.08)", + "use": "Secondary buttons" + }, + "hover": { + "value": "rgba(255,255,255,.045)", + "use": "A row under the pointer" + }, + "selected": { + "value": "rgba(255,255,255,.075)", + "use": "The selected row" + }, + "segment": { + "value": "#3d3f45", + "use": "The chosen segment of a segmented control" + }, + "segmentInGroup": { + "value": "#4a4c53", + "use": "The chosen segment inside a settings group" + }, + "switchOff": { + "value": "rgba(255,255,255,.14)", + "use": "A switch that is off" + }, + "grid": { + "value": "rgba(255,255,255,.045)", + "use": "Canvas dots, 1 px every 20 px" + } + }, + "line": { + "hairline": { + "value": "rgba(255,255,255,.05)", + "use": "Separators inside a card" + }, + "card": { + "value": "rgba(255,255,255,.06)", + "use": "The edge of a card" + }, + "control": { + "value": "rgba(255,255,255,.07)", + "use": "The edge of an input" + }, + "strong": { + "value": "rgba(255,255,255,.1)", + "use": "Floating surfaces" + } + }, + "text": { + "strong": { + "value": "#ffffff", + "use": "Titles, the chosen segment" + }, + "primary": { + "value": "#e6e7ea", + "use": "Body text" + }, + "body": { + "value": "#d6d8dc", + "use": "Labels in settings rows" + }, + "secondary": { + "value": "#9a9ea7", + "use": "Descriptions, unchosen segments" + }, + "tertiary": { + "value": "#80858e", + "use": "Section captions, metadata" + }, + "quiet": { + "value": "#6f747d", + "use": "Hints, footnotes" + }, + "disabled": { + "value": "#4d5058", + "use": "Disabled text, power pins" + }, + "onAccent": { + "value": "#062430", + "use": "Text on a cyan button" + } + }, + "accent": { + "base": { + "value": "#64d2ff", + "use": "The one action colour: primary buttons, selection, focus" + }, + "link": { + "value": "#7cc4ff", + "use": "Links and quiet actions" + }, + "text": { + "value": "#a8e4fb", + "use": "Text on an accent tint" + }, + "tint": { + "value": "rgba(100,210,255,.14)", + "use": "Accent backgrounds" + } + }, + "state": { + "success": { + "base": "#34c759", + "text": "#7fe3a0", + "tint": "rgba(52,199,89,.14)", + "edge": "rgba(52,199,89,.35)", + "use": "Passed, valid, connected, running" + }, + "warning": { + "base": "#e2b34f", + "text": "#ecc985", + "tint": "rgba(226,179,79,.1)", + "edge": "rgba(226,179,79,.4)", + "use": "A conflict, halted, a check to read" + }, + "danger": { + "base": "#f0736b", + "text": "#f6b4ae", + "tint": "rgba(240,115,107,.1)", + "edge": "rgba(240,115,107,.35)", + "use": "Failed, a fault, a rule broken" + }, + "kernel": { + "base": "#ffd60a", + "text": "#ffe27a", + "tint": "rgba(255,214,10,.14)", + "edge": "rgba(255,214,10,.4)", + "use": "Kernel-owned things: the tick, ceilings, the current line" + } + }, + "peripheral": { + "uart": { + "value": "#64d2ff", + "use": "USART and UART" + }, + "i2c": { + "value": "#bf8cff", + "use": "I2C" + }, + "spi": { + "value": "#ff6482", + "use": "SPI" + }, + "gpioOut": { + "value": "#34c759", + "use": "GPIO outputs, LEDs" + }, + "gpioIn": { + "value": "#66d4cf", + "use": "GPIO inputs, buttons" + }, + "adc": { + "value": "#5e9cff", + "use": "ADC and DAC" + }, + "timer": { + "value": "#ffd60a", + "use": "Timers" + }, + "debug": { + "value": "#98989f", + "use": "SWD, JTAG, trace" + } + }, + "syntax": { + "text": { + "value": "#d9dde3" + }, + "keyword": { + "value": "#c792ea" + }, + "function": { + "value": "#f5c97a" + }, + "type": { + "value": "#8cb4ff" + }, + "macro": { + "value": "#7fd3e8", + "use": "EMB_ names and register fields" + }, + "string": { + "value": "#b5d98c" + }, + "number": { + "value": "#f2a36b" + }, + "comment": { + "value": "#646b77" + } + } + }, + "type": { + "family": { + "ui": { + "value": "Inter", + "fallback": [ + "SF Pro Text", + "system-ui" + ] + }, + "mono": { + "value": "JetBrains Mono", + "fallback": [ + "SF Mono", + "Menlo" + ] + }, + "cjk": { + "value": "PingFang SC", + "fallback": [ + "Noto Sans SC", + "Microsoft YaHei" + ], + "use": "Chinese text, after Inter: PingFang SC on macOS, Noto Sans SC bundled for Windows and Linux. Latin text in a Chinese interface stays in Inter." + } + }, + "scale": { + "display": { + "size": 24, + "line": 30, + "weight": 800, + "tracking": "-0.01em", + "use": "A board's name on Start" + }, + "title1": { + "size": 22, + "line": 28, + "weight": 700, + "tracking": "-0.01em", + "use": "A settings page" + }, + "title2": { + "size": 18, + "line": 24, + "weight": 700, + "tracking": "-0.01em", + "use": "The inspector's subject, a run" + }, + "title3": { + "size": 15, + "line": 21, + "weight": 700, + "use": "A card's title" + }, + "body": { + "size": 13, + "line": 19, + "weight": 400, + "use": "Everything by default" + }, + "bodySmall": { + "size": 12.5, + "line": 18, + "weight": 400, + "use": "Settings labels, banners" + }, + "small": { + "size": 12, + "line": 17, + "weight": 400, + "use": "Descriptions, status bars" + }, + "meta": { + "size": 11.5, + "line": 16, + "weight": 400, + "use": "Second lines in lists" + }, + "caption": { + "size": 11, + "line": 14, + "weight": 600, + "tracking": "0.05em", + "case": "upper", + "use": "Section captions" + }, + "code": { + "size": 12, + "line": 18, + "weight": 400, + "family": "mono", + "use": "Source, disassembly, memory: VS Code's metrics on macOS" + }, + "codeMeta": { + "size": 10.5, + "line": 14, + "weight": 400, + "family": "mono", + "use": "Keys, addresses, pin lines on cards" + }, + "pin": { + "size": 8.5, + "line": 12, + "weight": 400, + "family": "mono", + "use": "Pin names on the chip; 600 when the pin is in use" + } + } + }, + "space": { + "unit": 2, + "scale": [ + 2, + 4, + 6, + 8, + 10, + 12, + 14, + 16, + 20, + 24, + 28 + ], + "gutter": 6, + "cardPadding": [ + 12, + 16 + ], + "use": "Cards sit 6 px apart and 6 px from the window edge" + }, + "radius": { + "segment": 5, + "control": 7, + "button": 8, + "track": 9, + "group": 10, + "card": 12, + "window": 14, + "pill": 999 + }, + "size": { + "titlebar": 50, + "cardHeader": 46, + "editorHeader": 42, + "statusbar": 32, + "row": 32, + "rowCompact": 24, + "control": 26, + "button": 30, + "buttonLarge": 36, + "switch": [ + 36, + 21 + ], + "dot": 7, + "activityBar": 48, + "codeLine": 18 + }, + "elevation": { + "flat": { + "value": "none", + "use": "Cards: an edge, no shadow" + }, + "raised": { + "value": "0 8px 20px rgba(0,0,0,.38)", + "use": "Cards on a canvas" + }, + "selected": { + "value": "0 0 0 4px , 0 14px 30px rgba(0,0,0,.5)", + "use": "The selected card on a canvas" + }, + "floating": { + "value": "0 14px 34px rgba(0,0,0,.5)", + "use": "Toasts, menus" + }, + "window": { + "value": "0 30px 80px rgba(0,0,0,.55)", + "use": "Sheets and windows" + }, + "knob": { + "value": "0 1px 2px rgba(0,0,0,.4)", + "use": "The chosen segment, a switch's knob" + } + }, + "motion": { + "rule": "Motion lasts 200 to 400 ms, eases out, and starts where the cause is. Nothing loops unless it shows something live.", + "hover": { + "duration": 120, + "easing": "linear", + "use": "Row and button hover" + }, + "state": { + "duration": 200, + "easing": "ease-out", + "use": "Colours and fills changing: a switch, a segment, a status" + }, + "enter": { + "duration": 280, + "easing": "ease-out", + "offset": 5, + "use": "Something new appears: it rises 5 px and fades in" + }, + "move": { + "duration": 350, + "easing": "cubic-bezier(.2,.8,.2,1)", + "use": "Something changes place: a thread to a new priority, a zoom" + }, + "draw": { + "duration": 300, + "easing": "ease-out", + "stagger": 280, + "use": "A route draws itself, segment after segment" + }, + "fill": { + "duration": 400, + "easing": "cubic-bezier(.2,.8,.2,1)", + "use": "A bar or ring fills to a new value" + }, + "stamp": { + "duration": 550, + "easing": "cubic-bezier(.2,.8,.2,1)", + "use": "The hardware seal, and nothing else" + }, + "live": { + "duration": 2200, + "easing": "ease-out", + "loop": true, + "use": "A connected board's pulse, a running target" + } + }, + "locale": { + "rule": "The app ships in English, French and Simplified Chinese. Every visible string comes from a Qt translation file (.ts, built with Qt Linguist); none is written into a layout. The language is chosen in Settings and applies without a restart.", + "languages": { + "value": [ + "en", + "fr", + "zh-Hans" + ], + "source": "en", + "use": "English is the source language; French and Simplified Chinese are translations of it." + }, + "expansion": { + "value": 1.35, + "use": "Layouts leave room for text 35% longer than English (French runs longest). Labels never get a fixed width; they wrap or elide, with the full text in a tooltip." + }, + "neverTranslated": { + "value": [ + "option keys (CONFIG_EMB_*)", + "register and field names", + "pin names", + "file names and paths", + "spec references (KRN-SCH-036)", + "code" + ], + "use": "These stay as they are in every language, in the mono family." + }, + "numbers": { + "use": "Numbers, dates and units follow the chosen language (QLocale): 115,200 or 115 200. Hex values and addresses never change." + }, + "chinese": { + "lineBreak": "Chinese breaks between characters, not at spaces; Qt's text layout does this when the locale is zh-Hans.", + "size": "Chinese text uses the same sizes as Latin text, never smaller than 12 px: the 11 px caption becomes 12 px, without capitals or letter spacing.", + "punctuation": "Full-width punctuation (,。:) inside Chinese sentences; technical names inside them keep their own form.", + "use": "Chinese labels are usually shorter than English, so the room left for French covers them. Chinese reads left to right: no layout is mirrored." + } + } +}