DOL Organizer Kit - AI Guideline

active v1Updated3 tuần trước

Canvas-organization layer for Figma design sessions. Components for wrapping screens with level banners, connecting flows with arrows, placing dev/design notes, and spec annotation.

Different from DS V2: DS V2 = UI building blocks (Button/Input/Modal); Organizer Kit = canvas meta-layer (Design area banners, flow arrows, notes). Both coexist. When building a real UI surface → DS V2. When arranging designs on canvas → Organizer Kit.

Source

Figma file: DOL's Design Organizer Kit (key NxdDuGawc6P4d9ffKCoCZ1)
67 components total (35 standalone + 32 sets) across 10 canonical categories

File structure

File	Purpose
`component-registry.md`	Slim INDEX - all 10 categories with 3-key preview each (~140 lines)
`components/<category>.md`	10 detail files with full variant property schemas
`components/_index.json`	Machine catalog consumed by `lookup.py organizer`
`usage-patterns.md`	Hand-authored - layout rules, when to use which component, anti-patterns (CRITICAL read for AI agents)
`cache/organizer-inventory.json`	Gitignored - raw Figma extraction dump
`tools/extract-organizer-metadata.py`	Generator (reads cache → emits registry + detail files + machine JSON)

Tier classification (for AI context budget)

Tier	Files	When to load
TIER 0 - CLI	`python3 ../tools/lookup.py organizer <name>` or `... organizer-list <category>`	Looking up ONE component / listing a category (cheapest, ≤500 tokens)
TIER 1 - Always-on for organizer tasks	`usage-patterns.md` (~220 lines) + `component-registry.md` (~140 lines)	User says “arrange designs on canvas” / “add notes to design session” / “document user flow”
TIER 2 - On-demand detail	`components/<category>.md` (20-45 lines each)	Need variant property schema for specific category

The 10 categories

Slug	Primary use
`design-area`	Level 1/2/3 banners grouping screens by flow hierarchy
`design-notes`	Boxed dev/design notes (Style 1/2, Type = Note for dev / Design note / Flow note / etc.)
`arrows`	Flow direction + Element note + Breakdown arrows connecting screens
`state-notes`	Compact state labels (State note simple / State note 2)
`token-notes`	Token annotations (“this color = `text-color/danger-primary`”)
`element-notes`	Anotate bubbles pointing at elements (rare - prefer Design note Box for longer content)
`animation-notes`	9 direction arrows for animation entry (from top/bot/left/right/corners/center)
`guide-areas`	Inline block notes (purple/blue/green) for grouping annotations
`guideline-support`	Ruler / Dimension marks / Spacing marks / 18 cursor variants
`ux-kit`	UX doc flowchart + FigJam smart connector

Canvas layout pattern (user-confirmed)

[Level 1 banner - e.g., "Mở đầu"]
     │
     ▼  (screens belonging to this flow placed below)
┌────────┐  ───►  ┌────────┐  ───►  ┌────────┐
│ Screen │        │ Screen │        │ Screen │
│   1    │        │   2    │        │   3    │
└────────┘        └────────┘        └────────┘

→ Full rules in usage-patterns.md.

Re-sync

When DS team adds/removes Organizer components:

Open Organizer Kit in Figma with Desktop Bridge plugin
Run figma_execute extraction (see tools/extract-organizer-metadata.py header comments)
Save output to cache/organizer-inventory.json
Run python3 tools/extract-organizer-metadata.py
Commit component-registry.md + components/ (cache stays gitignored)

../README.md - DS V2 components (UI building blocks)
../tools/lookup.py - CLI with organizer + organizer-list subcommands
../../ai-entry/FIGMA-AI.md - AI agent router (TIER 0-3 table includes Organizer paths)
usage-patterns.md - layout rules + anti-patterns