davidl/tolaria
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

design: design system proposal + canvas reorganization

Browse Source 
- Reorder frames in ui-design.pen for better spatial organization
- Add docs/DESIGN-SYSTEM-PROPOSAL.md: full design system analysis and roadmap
  - Identifies 13 duplicated patterns (NoteList/Item x10, Inspector headers x7, etc.)
  - Proposes atomic structure: atoms → molecules → organisms
  - 6-phase implementation plan (16-22h total, phases 1-3 = 80% value)
  - Naming conventions, component inventory, canvas layout strategy
This commit is contained in:
lucaronin
2026-02-26 10:22:34 +01:00
parent 17e9cb1a8e
commit 9da7cf5182
2 changed files with 3692 additions and 5599 deletions
Download Patch File Download Diff File Expand all files Collapse all files

352
docs/DESIGN-SYSTEM-PROPOSAL.md Normal file
View File

@@ -0,0 +1,352 @@
# Design System Proposal for Laputa
## Current State Assessment
### What exists today
- **53 top-level frames** scattered across a ~6800x11400px canvas with no spatial logic
- **0 reusable components** (every frame is ad-hoc)
- **~40 design variables** with light/dark theme support (colors, radii, fonts)
- **2 foundation frames**: Color Palette and Typography & Spacing Specs
- **1 full-app layout** frame (light mode only)
- **4 sidebar-collapse variations** showing different panel states
### Recurring patterns that should be components (but aren't)
By analyzing the 53 frames, these patterns are duplicated 3-10x each:
| Pattern | Where it appears | Times duplicated |
|---------|-----------------|-----------------|
| Inspector section header (label + action icon) | rbF01-03, reF01-03, pi01 | 7x |
| Note list item (title + snippet + date + dot) | dp01-04, mni01-04, trNL1 | ~10x |
| Tab bar tab (label + close + dot indicator) | dp10, mni10, full layout | 3x |
| Sidebar filter item (icon + label + count) | trSB1, full layout sidebar | 4x |
| Sidebar section group (chevron + icon + label) | full layout, drag frames | 4x |
| Breadcrumb bar (icon + path + badges) | dp20, archBtnNorm/Arc, full layout | 4x |
| Modal shell (header + body + footer) | ghv01-04, iogBH (settings) | 5x |
| Property row (label + value) | urlDefault/Hover/Edit, pi01 | 4x |
| Relationship pill (icon + label + X) | trRI1, reF01-03, rbF01-03 | 6x |
| Status badge (colored dot/pill) | dp01, dp10, dp20, dp30 | 4x |
| Status bar (version + branch + sync) | mni20, full layout | 2x |
| Search bar (dark themed) | 3aG9b, K1O2x, nrIcZ | 3x |
| Warning/info banner | trW30 | 1x (but will recur) |
Every time a new feature is designed, these get rebuilt from scratch.
---
## Proposed Structure
### Single file: `ui-design.pen`
Multiple files creates friction (can't reference components cross-file, harder to maintain). Keep one file, organized into logical **sections** using large container frames as visual grouping. Each section is a horizontal band across the canvas.
### Canvas Layout (top to bottom)
```
y ≈ 0 ┌─────────────────────────────────────────────┐
│ 0. COVER │
│ App name, version, last updated, TOC │
└─────────────────────────────────────────────┘
y ≈ 200 ┌─────────────────────────────────────────────┐
│ 1. FOUNDATIONS │
│ Color palette, Typography scale, Spacing, │
│ Border radius, Shadows, Iconography │
└─────────────────────────────────────────────┘
y ≈ 1800 ┌─────────────────────────────────────────────┐
│ 2. COMPONENTS (Reusable) │
│ Atoms → Molecules → Organisms │
│ Each component: default + states side by side│
└─────────────────────────────────────────────┘
y ≈ 5000 ┌─────────────────────────────────────────────┐
│ 3. PATTERNS / COMPOSITIONS │
│ Panel Inspector, Panel NoteList, Panel Editor│
│ Modal shell, Popover/dropdown shell │
└─────────────────────────────────────────────┘
y ≈ 7000 ┌─────────────────────────────────────────────┐
│ 4. FULL LAYOUTS │
│ Default state, Sidebar collapsed, Editor │
│ only, etc. (full 1440x900 frames) │
└─────────────────────────────────────────────┘
y ≈ 12000 ┌─────────────────────────────────────────────┐
│ 5. FEATURE SPECS │
│ Grouped by feature area — all current 53 │
│ frames reorganized here │
└─────────────────────────────────────────────┘
```
Each section starts with a **section label frame** (large text, description, horizontal rule). Within each section, frames flow **left to right, wrapping down**, with 100px spacing.
---
## Section 1: Foundations
### What to keep
- **Color Palette** (frame `mOf4J`) — already good. Move to top of file.
- **Typography & Spacing** (frame `HZonq`) — already good. Place next to color palette.
### What to add
- **Spacing Scale** — explicit 4px grid reference (4, 8, 12, 16, 20, 24, 32, 40, 48, 64) with visual boxes
- **Shadow Tokens** — overlay shadow, dialog shadow, dropdown shadow (currently only documented in CSS, not in the design file)
- **Icon Reference** — small grid showing common Lucide + Phosphor icons used in the app, at 14px and 16px sizes
### Variables to add
The .pen file already has `--radius-sm/md/lg` but is missing spacing variables. Add:
| Variable | Value | Usage |
|----------|-------|-------|
| `--space-xs` | 4 | Tight gaps (icon-to-label) |
| `--space-sm` | 8 | Standard gap |
| `--space-md` | 12 | Section padding |
| `--space-lg` | 16 | Panel padding |
| `--space-xl` | 24 | Large section gaps |
| `--space-2xl` | 32 | Page padding |
| `--space-3xl` | 48 | Section dividers |
---
## Section 2: Component Library
### Atomic Design Hierarchy
#### Atoms (smallest building blocks)
| Component | Variants/States | ID Prefix |
|-----------|----------------|-----------|
| **Button/Primary** | default, hover, active, disabled | `c/btn-pri` |
| **Button/Secondary** | default, hover, active, disabled | `c/btn-sec` |
| **Button/Ghost** | default, hover, active | `c/btn-ghost` |
| **Button/Destructive** | default, hover, disabled | `c/btn-dest` |
| **Button/Icon** | default, hover (icon-only button, e.g. close, settings) | `c/btn-icon` |
| **Input/Text** | empty, filled, focused, error, disabled | `c/input` |
| **Input/Search** | empty, with query, with clear button | `c/input-search` |
| **Badge** | default, secondary, outline, destructive, status colors (green/orange/red/blue/purple) | `c/badge` |
| **Status Dot** | green (new), orange (modified), none (clean) | `c/status-dot` |
| **Checkbox** | unchecked, checked, indeterminate | `c/checkbox` |
| **Toggle** | off, on | `c/toggle` |
| **Icon** | 14px, 16px, 20px wrapper with Lucide/Phosphor | `c/icon` |
| **Separator** | horizontal, vertical | `c/sep` |
| **Avatar/Initial** | letter avatar for Person entities | `c/avatar` |
| **Tooltip** | top, bottom (container with pointer) | `c/tooltip` |
#### Molecules (composed from atoms)
| Component | Composition | States | ID Prefix |
|-----------|------------|--------|-----------|
| **Sidebar/FilterItem** | icon + label + count badge | default, active, hover | `c/sb-filter` |
| **Sidebar/SectionHeader** | chevron + icon + label + add button | collapsed, expanded, hover, dragging | `c/sb-section` |
| **Sidebar/SectionItem** | indent + label | default, active, hover | `c/sb-item` |
| **Sidebar/TopicItem** | hash + label | default, active, hover | `c/sb-topic` |
| **NoteList/Item** | status dot + title + snippet + date + type pill | default, selected, hover, modified, new | `c/nl-item` |
| **NoteList/Header** | title + count + sort button | — | `c/nl-header` |
| **Tab** | label + close btn + modified dot | default, active, hover, modified | `c/tab` |
| **BreadcrumbBar** | path segments + word count + status badge | new, modified, clean | `c/breadcrumb` |
| **Property/Row** | label + value | default, hover, editing | `c/prop-row` |
| **Property/URLRow** | label + link + copy/edit icons | default, hover, editing | `c/prop-url` |
| **Relationship/Pill** | icon + label + (X remove on hover) | default, hover, trashed, archived | `c/rel-pill` |
| **Relationship/AddInput** | search input with autocomplete | empty, typing, results | `c/rel-add` |
| **Inspector/SectionHeader** | label + action button | default, hover | `c/insp-header` |
| **Git/CommitItem** | hash + message + author + date (timeline style) | — | `c/git-commit` |
| **Search/ResultItem** | title + path + highlighted snippet | default, selected | `c/search-result` |
| **Sort/DropdownItem** | label + direction arrow + checkmark | default, selected | `c/sort-item` |
| **Banner/Warning** | icon + message + optional action | info, warning, error | `c/banner` |
| **Wikilink** | colored link text (varies by entity type) | 8 type colors | `c/wikilink` |
#### Organisms (panel-level compositions)
| Component | Content | ID Prefix |
|-----------|---------|-----------|
| **Panel/Sidebar** | title bar + filters + sections + commit area | `c/panel-sidebar` |
| **Panel/NoteList** | header + type pills + item list | `c/panel-notelist` |
| **Panel/Editor** | tab bar + breadcrumb + content area | `c/panel-editor` |
| **Panel/Inspector** | properties section + relations + backlinks + history | `c/panel-inspector` |
| **Modal/Shell** | header + tab bar (opt) + body + footer | `c/modal` |
| **Popover/Dropdown** | list of items + separator + annotation | `c/popover` |
| **StatusBar** | left info + right info | `c/statusbar` |
| **TitleBar** | traffic lights (macOS) | `c/titlebar` |
---
## Section 3: Patterns / Compositions
These are **non-reusable** reference frames showing how components compose into real UI sections. Think of them as "component playgrounds" — they use component instances to build real UI, but they're documentation, not building blocks.
- **Inspector states**: Properties expanded, Relations with pills, Referenced By with/without entries, Backlinks, Git history
- **NoteList states**: All Notes view, filtered by section, empty state, search results
- **Sidebar states**: All sections expanded, one collapsed, dragging reorder, after reorder
- **Editor states**: Single tab, multiple tabs, modified tabs, diff view
- **Modal patterns**: GitHub Vault flow (4 states), Settings, Create Note, Commit Dialog
---
## Section 4: Full Layouts
| Frame | Description |
|-------|-------------|
| **Default — All Panels** | 1440x900, sidebar + notelist + editor + inspector |
| **Sidebar Collapsed** | Editor area wider, collapse button visible |
| **Editor + NoteList Only** | No sidebar or inspector |
| **Editor Only** | Focused writing mode |
| **AI Chat Open** | Inspector replaced with AI Chat panel |
| **Quick Open Modal** | Cmd+P overlay on default layout |
Keep the existing 5 layout frames (qHhaj + SC_all/nosb/edonly/ednl). Add AI Chat and Quick Open.
---
## Section 5: Feature Specs
Reorganize existing 53 frames into feature groups. Each group gets a **feature label** frame above it:
| Group | Frames to include |
|-------|-------------------|
| **Note Status & Indicators** | dp01, dp10, dp20, dp30, mni01, mni10, mni20 |
| **Trash & Archive** | trSB1, trNL1, trRI1, trW30, archBtnNorm, archBtnArc |
| **Inspector & Properties** | pi01, pi50, rbF01-03, reF01-03, urlDefault/Hover/Edit |
| **Sidebar** | dsg01a-04j, csB01, csA01 |
| **GitHub Vault** | ghv01-04, ghv03 |
| **Git History** | ghCL1, ghDO1, vc001, vc100, vc200 |
| **Sort & Search** | srtDD, srtBN, 3aG9b, K1O2x, nrIcZ |
| **Editor & Wikilinks** | wlc01 |
| **Settings** | iogBH |
| **Virtual List** | vl001 |
---
## Naming Convention
### Frames
```
Section-level: "== FOUNDATIONS =="
"== COMPONENTS =="
"== FULL LAYOUTS =="
Feature groups: "Feature: Trash & Archive"
"Feature: Note Status"
```
### Reusable Components
```
component/<category>/<name>
Examples:
component/button/primary
component/button/ghost
component/sidebar/filter-item
component/notelist/item
component/inspector/section-header
component/modal/shell
```
### States (within a component frame)
```
<component-name> — <state>
Examples:
Button/Primary — Default
Button/Primary — Hover
NoteList/Item — Selected
NoteList/Item — Modified
```
### Feature Spec Frames
```
<Feature> — <Specific View>
Examples:
Trash — Note List View
Trash — 30-Day Warning
Git History — Commit List
Git History — Diff Open
```
---
## Implementation Priority
### Phase 1: Foundation Cleanup (2-3 hours)
1. Add spacing variables to the .pen file
2. Move Color Palette and Typography frames to top of canvas (y ≈ 200)
3. Add section label frames as visual dividers
4. Reorganize existing 53 frames into the feature-spec section (y ≈ 12000+)
5. Create cover frame at y ≈ 0
**Impact**: Clean canvas, easy to navigate. Zero component work yet.
### Phase 2: Core Atoms (3-4 hours)
1. **Button** — 4 variants x 3 states = ~12 sub-frames, all as `reusable: true`
2. **Badge** — 6 color variants + 4 style variants
3. **Status Dot** — green, orange, red, none
4. **Input** — text + search variants
5. **Separator** — horizontal + vertical
6. **Icon Button** — close, settings, chevron, etc.
**Impact**: Building blocks exist. Future features can pull from them.
### Phase 3: Core Molecules (4-5 hours)
1. **Sidebar/FilterItem** — most reused sidebar pattern
2. **Sidebar/SectionHeader** — with chevron and add button
3. **NoteList/Item** — the most duplicated pattern in the file
4. **Tab** — with modified indicator states
5. **Property/Row** — default/hover/edit states
6. **Relationship/Pill** — normal/trashed/archived states
7. **Inspector/SectionHeader** — label + collapse/action
**Impact**: Feature specs can be rebuilt from instances. Consistency guaranteed.
### Phase 4: Organisms (3-4 hours)
1. **Modal/Shell** — replace 5 ad-hoc modals with instances of one shell
2. **Panel/Sidebar** — full sidebar composition
3. **Panel/NoteList** — full notelist composition
4. **StatusBar** — standardize
5. **Popover/Dropdown** — for sort, autocomplete, etc.
**Impact**: Full layouts can be composed from panel organisms.
### Phase 5: Rebuild Full Layouts (2-3 hours)
1. Rebuild "Laputa App — Full Layout (Light)" using component instances
2. Create remaining layout variants (AI Chat, Quick Open)
3. Ensure all layouts use the same component instances for consistency
**Impact**: Single source of truth. Change a button component, all layouts update.
### Phase 6: Feature Spec Cleanup (2-3 hours)
1. Rebuild key feature specs using component instances where possible
2. Remove frames that are now redundant (covered by component states)
3. Add any missing feature-specific variations
**Impact**: Clean, maintainable feature documentation.
---
## Estimated Total Effort
| Phase | Effort | Cumulative |
|-------|--------|-----------|
| 1. Foundation Cleanup | 2-3h | 2-3h |
| 2. Core Atoms | 3-4h | 5-7h |
| 3. Core Molecules | 4-5h | 9-12h |
| 4. Organisms | 3-4h | 12-16h |
| 5. Full Layouts | 2-3h | 14-19h |
| 6. Feature Cleanup | 2-3h | 16-22h |
**Recommendation**: Do phases 1-3 first (9-12h). This covers 80% of the value — clean organization + the most reused components. Phases 4-6 can happen incrementally as features are designed.
---
## What "World Class" Looks Like
After this work, `ui-design.pen` will:
1. **Open to a cover page** with app identity and section navigation
2. **Have ~30 reusable components** that match the real implementation 1:1
3. **Use variables everywhere** — no hardcoded colors, spacing, or radii
4. **Show every component state** — no guessing what hover/active/disabled looks like
5. **Compose layouts from instances** — change a component, all layouts update
6. **Group features logically** — find any feature spec in seconds
7. **Grow naturally** — new features just add instances of existing components + new feature-specific frames
The key shift: **from "collection of screenshots" to "living system of composable parts"**.

8939
ui-design.pen
View File

File diff suppressed because it is too large Load Diff