Organizer Kit - Usage Patterns

activeUpdated3 tuần trước

Hand-authored rules for arranging designs on canvas. Complement to component-registry.md (which lists WHAT components exist).

§1 Mental model

The Organizer Kit is a canvas-organization layer, orthogonal to the UI building blocks in DS V2. When you’re building a real UI surface (Button, Modal, etc.) → use DS V2. When you’re arranging + documenting a design session on a Figma page → use Organizer Kit.

Two concerns handled by the Kit:

Grouping - which screens belong together under one flow/feature label (Design area)
Annotation - dev notes, design notes, flow arrows, element labels (Design note, Arrows, etc.)

§2 Design area hierarchy - the most important pattern

Design area/Main (All in one) has a Level variant with 3 values: 1, 2, 3. Use as hierarchy:

Level 1 = top banner - the flow / feature / major section. Most prominent color (usually Red for Design type).
Level 2 = sub-banner - a group within Level 1 (e.g., sub-flow). Same Title area, slightly smaller weight.
Level 3 = deepest sub-group - rare; only when Level 2 has its own breakdown.

Canvas layout rule

Design area goes ABOVE, screens go BELOW. User-confirmed pattern:

┌─────────────────────────────────────────────────────────┐
│  [Level 1 banner]  Mở đầu                               │   ← Design area/Main, Level=1
└─────────────────────────────────────────────────────────┘
      │
      ▼ (screens that belong to this flow below the banner)
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ Chọn    │   │ Loading │   │ Setting │
   │ ngôn    │   │         │   │         │
   │ ngữ     │   │         │   │         │
   └─────────┘   └─────────┘   └─────────┘

If one of those screens has its own internal flow → place a Level 2 banner above that subgroup:

┌──────── [Level 1]  Mở đầu ────────────────────────────┐
│                                                       │
│   ┌─ [Level 2] Setting sub-flow ───────────────┐      │
│   │    ┌─────┐  ┌─────┐  ┌─────┐              │      │
│   │    │ S1  │  │ S2  │  │ S3  │              │      │
│   │    └─────┘  └─────┘  └─────┘              │      │
│   └────────────────────────────────────────────┘      │
└───────────────────────────────────────────────────────┘

Which Type to pick (DOL canonical - 3 types)

🛑 DOL convention: chỉ dùng 3 Type cho 95% case. Confirmed user 2026-04-27.

Type	Khi nào dùng	Ví dụ
`Design`	Area normal - flow chính, happy path, sub-flow, mọi banner không phải error/note	”Mở đầu”, “Gợi ý sẵn cấu trúc”, “User nói → Phân tích”, “Đúng cấu trúc - Tuyệt vời”
`Negative`	Area liên quan đến error / sai / edge case	”Sai → Nói lại”, “Làm sai - nhiều trường hợp”, “Sai đề / Ít từ”
`Note`	Area về note tính năng - thông tin/giải thích, không phải UI flow	”Note: Karaoke timing”, “Note: Pronunciation roadmap”

Rule: pick Type first (semantic). 3 types cover 95% DOL design sessions.

Other types (rare - dùng khi có nhu cầu cụ thể)

13 Type variants tổng cộng. 10 còn lại dùng rất hiếm trong production:

Type	Khi xài (rare)
`Interaction`	Prototype / hover demos
`Update`	Version / release tag (e.g., “Update 154 jun 2024”)
`Responsive`	Viewport breakdown variants
`Flow` / `Component`	Popup / modal-specific section (alternate to Design+blue color)
`Function note` / `Function` / `Spec` / `Layout` / `Test` / `Feedback`	Reserved cho special cases - default về Design/Negative/Note nếu không chắc

Color (secondary decision - visual emphasis only)

9 Colors × 13 Types = 117 combos available. Color picked AFTER Type, không thay thế Type:

Red (default) - paired with Design for canonical main flow
Rose / Neutral - sub-banner (Level 2) within Level 1
Green - paired với Negative for error states
Blue - paired với Note or Flow for info/popup sections
Lemon - paired với Update for release marker
Turquoise / Purple / Orange - rare, semantic match needed

Rule: don’t mix semantic purposes with “same type but different color”. Type drives meaning; Color reinforces visually.

§3 Flow arrows - connecting screens

For screen-to-screen user flow documentation, use Note/Arrow/Element note/1..4 (with text label) or Note/Arrow/Flow direction/1..4 (no text, just arrow).

Which arrow type

Shape	Use when
`Flow direction/1` (4 variants: → ← ↓ ↑)	Simple straight arrow between 2 adjacent screens
`Flow direction/2` (8 variants, 1 bend)	Screen flows with a single turn (right-then-down, etc.)
`Flow direction/3` (8 variants, 2 bends)	Complex flow with 2 turns (rare; consider breaking into multiple simple arrows)
`Flow direction/4` (8 diagonal variants)	Diagonal connections when vertical/horizontal doesn’t fit layout
`Element note/1..4`	Same shapes + an editable text label on the arrow (use for “Click”, “On submit”, etc.)
`Breakdown note/1..4`	Same shapes + breakdown list of steps alongside arrow (for detailed flow decomposition)

Canvas layout pattern for flows

Screens in a flow arrange left-to-right typically, connected by right-arrows:

┌──────┐   ───►   ┌──────┐   ───►   ┌──────┐
│ S1   │          │ S2   │          │ S3   │
└──────┘          └──────┘          └──────┘

For branching (one screen → multiple outcomes), use different arrow direction per branch:

                    ┌──────┐   (path A)
                ───►│  A   │
┌──────┐            └──────┘
│ S1   │─┐
└──────┘ │
         │          ┌──────┐   (path B)
         └────────►│  B   │
                    └──────┘

Destination Frame (standalone component) marks the endpoint of a flow when the arrow leads to an off-canvas continuation.

§4 Notes alongside designs

§4.1 `Design note/Box note - Style 1` vs `Style 2`

Both are boxed note cards. Pick Style based on content shape:

Style 1 - simple header + body, optional icon + arrow. Most common.
Style 2 - supports “Related” section + “P/s” postscript. Use for dev notes with cross-references.

§4.2 Color-coded meaning (both styles)

Type note variant drives both icon and color theming. Pick by intent:

Type note	Default Color	Use for
`Note for dev`	Purple	Dev-facing implementation hint (logic, edge cases, API behavior)
`Design note`	Blue	Design decision rationale
`Flow note`	Cyan	Describing a user-flow step
`Responsive`	Orange	Breakpoint / viewport-specific behavior
`Component`	Green	”This uses component X with variant Y”
`Animation`	Pink	Motion spec (duration, easing, entry direction)
`Update`	Lemon / Yellow	Version / release marker
`Negative`	Red	Edge-case / error condition note
`Basic`	White	Generic note, no semantic type
`Other`	-	Catch-all

Convention: one Type per note. Don’t mix (e.g., don’t style a dev note with Responsive color).

§4.3 `State note simple` vs `State note 2`

Short text-label pointing at an element:

State note simple - 42 variants, multiple styles (State / Guide / Success / Warning / Danger / Neutral), 3 directions. Use for compact inline state markers.
State note 2 - 2 variants, supports optional detail note + area line. Use when you need to draw attention to a region + explain.

§4.4 `Token tag note`

Special case for annotating token choices (e.g., “this color = text-color/danger-primary”). Same style variants as State note but with token-tag visual treatment.

§5 Element notes (rare - use sparingly)

Design note/Anotate (60 variants) and Anotate 2 (6 variants) are orange-brown bubble labels pointing at a specific element. In user’s example samples, these appear as “Area section bg” / “Design area 1” / “Flow note” teaching labels.

Per user: this is rarely used in production design documentation. Mostly for onboarding / teaching designers “this is called X”. Don’t default to anotate; prefer Design note Box Style 1/2.

Avoid clutter: max 2 anotate labels per screen group. More = visual noise.

§6 Animation direction arrows

9 standalone arrows for documenting animation entry direction:

Arrow	Meaning
`↖ From right bot`, `↗ From left bot`, `↘ From left top`, `↙ From right top`	Entry from corner
`↑ From bot`, `← From right`, `↓ From top`, `→ From left`	Entry from edge
`⦿ From center`	Fade/scale from center

Place the arrow near the element + use together with Design note Type=Animation for full spec (duration, easing).

§7 Guideline support (ruler, dimensions, spacing, cursors)

Use when documenting spec-level detail:

Ruler - canvas measurement ruler
Guideline/Dimension/Horizontal - 8 variants: shows size of element (e.g., “99px wide”)
Guideline/Spacing mark/Horizontal - 16 variants: Padding / Margin / Area / Element spacing markers
18 cursor variants - for pointing out interactive affordances (“Clickable”, “Drag”, “Resize ↔”, etc.)

Don’t use on final design deliverable; use during spec handoff or for education.

§8 Guide areas (colored block notes)

3 standalone variants: Purple / Blue / Green Guide area, Block note. Inline colored blocks for grouping related annotations (e.g., “All these fields share the same validation rule”).

§9 UX Kit

For high-level flow documentation (like FigJam style):

UX doc/Flowchart note - 6 colors (Red/Yellow/Blue/Purple/Green/Turquoise) for flowchart-style nodes
Figjam Arrow, smart connector - standalone smart connector

Use when designing a full user journey visualization, not per-screen annotation.

§10 Anti-patterns

❌ Don’t	✅ Do
Mix Level 1 and Level 2 banners at the same visual weight	Level 1 = Red/bold; Level 2 = Rose/smaller; clear hierarchy
Dùng Type=Design cho area error states (“Sai → Nói lại”)	Type=Negative cho error/sai areas (DOL convention §2.4)
Dùng Type=Design cho area note tính năng	Type=Note cho note-only areas (không phải UI flow)
Pick exotic Type (`Interaction`, `Update`, `Layout`…) khi 3-type canonical đủ dùng	Default về Design/Negative/Note - chỉ chuyển khi semantic thực sự khớp
Use Design note Type=Design color=Red for a dev note	Match Type to Color semantic: dev → Purple, flow → Cyan
Plaster 5+ anotate bubbles on one screen	Max 2 anotate per screen; prefer Design note Box for longer content
Use `Flow direction/3` (2-bend arrow) when 2 simple arrows would read clearer	Break complex flow into multiple straight arrows
Leave `Status` subtext on Design area when design is Done	Set Status to `Done` explicitly OR hide the Status slot
Forget to place screens BELOW the design area banner they belong to	Always: banner above, screens below (user-confirmed pattern)
Use Token tag note for non-token annotations	Token tag note is RESERVED for “this value = ” callouts
Mix Organizer components with DS V2 components in the same frame	Organizer = canvas layer; DS V2 = UI content. Separate concerns.

§11 When unsure → ask user or skip annotation

The Organizer Kit has ~67 components across 10 categories. Not every design page needs all annotations. When unclear whether to annotate:

If the design is self-explanatory → skip annotation
If there’s a non-obvious dev/logic decision → add Design note Box Style 1 with Type=Note for dev
If the flow between screens isn’t obvious → add flow arrows
If a specific element needs attention → use State note simple (cheap) before Design note/Anotate (heavy)

component-registry.md - all 67 Organizer components indexed
components/<category>.md - per-category detail files with variant properties
README.md - folder overview + lookup.py CLI pointer
../../figma-ai/README.md - broader Figma AI system
User’s canvas samples (3 Listing / Loading / Xem chấm điểm examples) validated the Design area + flow arrow + Design note patterns documented here