tolaria/docs/DESIGN-SYSTEM-PROPOSAL.md

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".