353 lines
16 KiB
Markdown
353 lines
16 KiB
Markdown
|
# 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"**.
|