Pattern Registry - Named Composition Patterns

Mục đích: AI agents + designers/devs lấy nhanh named composition patterns đang có. Single-file index, mirror precedent của anti-pattern-registry.md placement.

Pattern ≠ Component: Pattern là recipe tổ hợp primitives trong cấu trúc cụ thể (1 pattern có thể chứa nhiều components). Component là atomic primitive (Button, Input, etc.). Cả 2 catalog-style retrievable, nhưng pattern có nội dung phong phú hơn.

Convention

• 1 entry per named pattern trong table dưới - quick description + link to detail recipe
• Detail recipe lives in most-relevant context file (e.g., landing patterns trong ui-style-guide/landing.md); registry = INDEX, detail = full recipe (avoid duplication)
• Naming uniqueness: tên phải distinguish from generic terms - Constellation Block (NOT Listing Block), Mosaic Catalog (NOT Grid Card), etc. - tương lai không clash
• Future scale trigger: khi pattern count ≥5, migrate to folder structure (patterns/ folder + per-file detail + _index.json machine catalog + generator). See “Migration trigger” section below.

Index

Name	Status	When to use (1-line)	Recipe detail	Recall triggers
Constellation Block	active	Catalog of ≥4 items với cấu trúc thông tin tương đương (program/feature/methodology) - outputs “ecosystem statement” 3-tier nested + star-effect gaps + optional bottom info row. Item count flexible: 4 (2×2) · 6 (3×2) · 8 (4×2).	ui-style-guide/landing.md §6.6	”use Constellation Block”, “ecosystem block kiểu dol.vn”, “3-tier nested catalog”, “build catalog với [N] programs/features”

Architecture mirror - pattern catalog vs component catalog

DOL system có 2 catalog-style retrieval mechanisms. Architecture parallel nhưng appropriate to type:

Concern	Pattern catalog (this file)	Component catalog (figma-ai/components/)
Storage layout	Single file (low count <5) → folder structure (≥5)	Folder: 1 INDEX file + 44 detail files + _index.json
Source-of-truth	Recipes live in product context (landing.md §X / practice.md §Y) - registry just indexes	Detail files mirror Figma DS components (auto-extracted)
Generator	Manual (small count) → automated when scale	extract-figma-metadata.py with --check gate
Retrieval entry	This file	component-registry.md (slim 465-line INDEX)
Granularity	Composition (1 pattern may use multiple components)	Atomic (single primitive or set)
Adapt to context	Decision matrices (variants × platform purpose) embedded in detail recipe	Variant props + states
Anti-patterns	XML scope pattern-<slug> in source file	XML scope <component-slug> in source file

→ Both unified by SHAPE (INDEX + retrieval entry + adapt-to-context decision tables) without forcing same physical folder.

Adding a new pattern (convention)

1. Define recipe trong most-relevant context file. Examples:
   • Landing pattern → ui-style-guide/landing.md §X.Y
   • Practice pattern → ui-style-guide/practice.md §X.Y
   • Data-entry pattern → ui-style-guide/data-entry.md §X.Y
   • Cross-product pattern (no clear product home) → ui-style-guide/CORE.md §X.Y OR new dedicated file
2. Append row to “Index” table above: name, status, when-to-use (1-line), recipe-link, recall triggers
3. Persist iteration history lesson at ai-memory/lessons/<pattern-slug>-pattern.md
4. Add anti-pattern XML scope pattern-<slug> in source file (if pattern has rules to enforce). Auto-extracts to anti-pattern-registry.md via extract-anti-patterns.py
5. Verify audit.sh clean + extract-anti-patterns.py --check passes
6. Optional: cross-link from related product files (e.g., if pattern relevant for both landing + practice)

Migration trigger - when to fold into folder structure

Migrate pattern-registry.md (single file) → patterns/ folder structure when ANY fires:

• Pattern count ≥5 active patterns codified
• Multi-product usage: same pattern used in ≥2 product surfaces (proof of cross-product nature)
• Variants explosion: ≥1 pattern has >5 variants - single-row table no longer sufficient
• Generator value: hand-maintenance becomes error-prone
• Context bloat: any single recipe >400 lines AND/OR product file >1000 lines AND agents typically read full file (not just specific anchor section). Anchor-targeted reads don’t count.

Migration steps (when triggered):

1. Create DOL-DS-token/design-guideline/patterns/ folder
2. Move each pattern detail recipe from product file → patterns/<slug>.md
3. Convert product file §X.Y → 3-line stub pointing to patterns/<slug>.md
4. Convert this registry → slim INDEX file (mirror figma-ai/components/component-registry.md shape)
5. Add patterns/_index.json machine catalog
6. Optional: add extract-pattern-metadata.py --check gate to pre-commit hook
7. Update lesson cross-refs

Until migration triggered: this single file scales OK (1 row per pattern, ~5-10 rows manageable).

Related

• Anti-pattern catalog: anti-pattern-registry.md (auto-gen, sibling at design-guideline root)
• Component catalog: figma-ai/components/component-registry.md (slim INDEX + 44 detail files + _index.json)
• Organizer catalog: figma-ai/organizer/README.md (10 detail files, separate canvas-meta layer)
• Variable catalog: figma-ai/variable-registry.md (auto-gen from tokens-data.json)
• Master overview hub: overview.md
• Style guide entry: ui-style-guide/CORE.md (primitives - what patterns compose from)
• Direction philosophy: ds-guideline/DIRECTION.md (anti-pattern + slop catalog)

Status

• Last reviewed: 2026-04-26
• Migration status: single-file (1 pattern) - folder migration not triggered
• Patterns count: 1 active
• Source files referenced: ui-style-guide/landing.md (§6.6 Constellation Block)
• Context-bloat watch: landing.md = 1262 lines (>1000 line trigger threshold). Currently NOT triggering split because Constellation Block (§6.6) accessed via anchor reads, not full-file. Re-evaluate when (a) 2nd named pattern joins landing.md, or (b) AI agents start full-loading landing.md as routine entry.