East Blue — Component Assessment Guide

Dependencies

01 — AI

Claude

Recommended: Claude Sonnet (latest). Paste this document as first-message context.

02 — Integration

Figma MCP Server

Direct file access. Minimum viewer access. Setup guide

03 — Source

Sticker Sheets v2

Open in Figma

04 — Build

Node.js

Run node assessment-src/build.js. No npm packages needed.

Never paste your Figma Personal Access Token into the chat. Authenticate via the MCP server setup.

DS Health — The 4 Traits

Each component is scored on 4 traits. These measure whether the component belongs in the design system and how well it's built.

Trait	What to Check
Reusable	Works across multiple contexts and flows — not tied to one screen or feature.
Self-contained	Carries its own styles, states, and logic without external dependencies.
Consistent	Predictable behavior. Naming, property types, and state coverage align with the DS.
Composable	Nests inside other components and fits the existing hierarchy.

Trait Ratings

Each trait gets one of four ratings. These describe how well the trait is met, not the component's overall health.

Rating	When to Use
Pass	Fully met. No issues — ready for native handoff.
Partial	Mostly met with minor gaps. Functional but has specific limitations (e.g. missing icon slots, but text variants work).
Warn	Significant concerns that limit reuse or block handoff (e.g. naming issues, raster assets, hardcoded values).
Fail	Broken. Blocks DS inclusion or native implementation entirely (e.g. flattened icons, no separable layers).

DS Verdicts

The overall DS Health outcome derived from all 4 trait ratings combined.

Verdict	Meaning
Keep	All 4 traits pass. Ship as-is.
Fix	Belongs in DS but has specific issues. Mostly pass/partial with a few warn.
Restructure	Needs significant property or architectural changes. Multiple warn/fail.
Consolidate	Merge into another component.
Product Layer	Too feature-specific for core DS.
Remove	Redundant, deprecated, or not a DS concern.

Native Mobile Readiness — 7 Criteria

Can engineers implement it in SwiftUI and Jetpack Compose? The overall status is set by the worst-scoring criterion.

ID	Criterion	What to Check
C1	Layer Structure & Naming	Layers should use semantic names like `leading-icon` or `content` — not Figma defaults like `Frame 42` or `Group 7`. Logical hierarchy, no unnecessary nesting.
C2	Variant & Property Naming	Variants and properties should follow clear, consistent conventions. Booleans as `true`/`false` (not `yes`/`no`), enum values lowercase and hyphenated.
C3	Token Coverage	All color, spacing, typography, and radius values should be bound to design tokens — not hardcoded. Token coverage determines how easily engineers can map to a native token system.
C4	Native Mappability	The component should map cleanly to a standard native primitive (e.g. `DisclosureGroup`, `Button`, `List`) with no web-only patterns.
C5	Interaction State Coverage	All expected interactive states should be defined as variants — default, pressed, focused, disabled, and error. Missing states force engineers to invent visual behavior.
C6	Asset & Icon Quality	Icons should be vector components (not raster or PNG embeds) and colored using tokens so tinting works natively on both platforms.
C7	Code Connect Linkability	The component should be a proper Figma component set with property names clean enough to map 1:1 to native parameters via Code Connect.

Native Status Levels

The overall native readiness of a component based on all 7 criteria.

Status	Meaning
Ready	Linkable as-is. Clean structure, maps well to native.
Needs Refinement	Minor issues to resolve before linking.
Requires Rework	Needs redesign before native translation.
Not Applicable	Web-only or removed — skip native assessment.
Fix	Resolved via Figma. Residual items may remain.

Combined Status

DS Health	Native Status	Meaning
Keep	Ready	Ship it.
Keep / Fix	Needs Refinement	Minor fixes, assign to DS team.
Fix / Restructure	Requires Rework	Significant work before handoff.
Product Layer	N/A	Move to product library.
Remove / Consolidate	N/A	Skip native assessment.

Report Architecture

The report is a modular, build-assembled static site on GitHub Pages.

Repository Structure

east-blue-design-system/
├── index.html                     ← Built output (do not edit)
├── styles.css                     ← Built output (minified)
└── assessment-src/
    ├── shell.html                 ← Shared layout, sidebar, JS
    ├── styles.css                 ← Source CSS (unminified)
    ├── build.js                   ← Build script
    └── components/
        ├── accordion.html         ← One file per component
        └── ...

Build Process

The build script reads shell.html as the scaffold, extracts 4 tagged blocks from each component file, injects them into the shell, minifies HTML + CSS, and writes to the repo root.

node assessment-src/build.js

GCash-Specific Patterns

Confirmed recurring patterns across the GCash DS. Use as a checklist during every assessment.

Naming & Properties (C2)

Boolean properties as strings — Should be true/false, not yes/no.

Space-separated variant names — Incompatible with Swift/Kotlin enums. Use hyphenated or camelCase.

Version numbers in names — transaction_v1, Type=Version 2 indicate cleanup debt.

Ambiguous sizes — size=default is unclear. Use named values (small, medium, large).

Overloaded property keys — A single type encoding style and layout should be split.

State values encoding style — State=Pill mixes concerns. Separate layout from interaction state.

Structure (C1, C4)

Generic layer names — Frame 42, Group 7, Placeholder should be semantic.

Non-component primitives — Boolean ops, flattened shapes, or bare groups where component sets are expected.

Feature variants as separate components — [Component] - with [Feature] should be a boolean property.

Baked-in content — Hardcoded content instead of composable slots.

Tokens (C3)

Hardcoded opacity — Use semantic opacity tokens, not raw values on layers.

Generic shadows — Shared Depth/D0 instead of component-specific tokens.

Raw pixel identifiers — Size 64 instead of named tokens like large.

Assets (C6)

Raster icons — Semantic icons as <img> from Figma CDN instead of vector instances. Hard C6 blocker.

States (C5)

Missing disabled — All interactive components need this.

Missing indeterminate — Checkboxes and radio groups.

Missing selected / active — Chips, toggles, tabs.

Incomplete state matrix — Every sub-type should cover all relevant states.

Figma Modes vs Component Properties (C2, C7)

Figma Modes are invisible in developer handoff. When a component uses Variable Collection Modes (e.g. Button's Appearance: Default / Destructive / White / Subtle), developers inspecting via Dev Mode or MCP see only the resolved CSS variable values — not the Mode itself.

A developer inspecting a Destructive Button sees background: var(--main/button/primary/destructive/enabled/bg), but does not see that the Button has 4 appearances, that "Appearance" is a Mode not a property, or how to switch between them in their native API.

Why this matters — Code Connect requires Mode → API parameter translation that must be written manually. A developer missing this context would only implement one appearance and not realize others exist.

Use Mode when — Appearance swap is global (dark theme, brand skin); variable reuse matters more than variant explosion; developers configure appearance at theme level.

Use Property when — Appearance is a per-instance choice (destructive, emphasis level); each appearance needs its own instance visible; developers configure appearance inline per call site.

Recommendation — For component-level appearance variants (destructive, outline, text, subtle), prefer component properties over Modes. Makes the variant matrix explicit in Figma, visible in dev handoff, and directly mappable to native API parameters without manual translation.

If Mode must stay — Document the Mode → API mapping explicitly in the component's Code tab, including every Mode value and its SwiftUI modifier / Compose parameter. Without this doc, the appearance layer is silently lost in handoff.

Known Good Patterns

Semantic color tokens — main/{component}/color/{state}/{role} is consistent.

Chevron icons — Confirmed vector component instances.

Spacing tokens — space/space-* consistently applied.

Custom fonts — Proxima Soft and BarkAda require native bundle verification. Flag once per session.

Discovered During Assessment

Criterion	Pattern	First Found In
C2	Boolean variant properties using yes/no strings instead of true/false	Accordion
C1	Root container frames left as Figma default "Frame"	Accordion
C1	Leading icon instances named "Placeholder" instead of semantic name	Accordion
C4	Expanded content panel added in v4 with content-body frame	Accordion

Assessment Workflow

For each Figma node URL received, follow these steps.

Step 1

Get Metadata

Count variants, read property names/values, spot C2 issues, understand layer hierarchy.

get_metadata(fileKey, nodeId)

Step 2

Get Screenshot

Visual confirmation. Identify missing states by what's absent.

get_screenshot(fileKey, nodeId)

Step 3

Get Design Context

Layer naming (C1), token usage (C3), raster icons (C6), layout structure (C4).

get_design_context(fileKey, nodeId,
  disableCodeConnect=true,
  clientFrameworks="SwiftUI, Jetpack Compose",
  clientLanguages="Swift, Kotlin")

Step 4

Get Token Definitions

Confirm token coverage (C3), extract hex values for the report.

get_variable_defs(fileKey, nodeId)

Step 5 — Optional

Spot-check Nodes

Verify if an element is a vector instance or raster.

get_metadata(fileKey, specificNodeId)

Step 6

Write Assessment

Score all 4 traits and 7 criteria. Assign verdicts. Output as markdown summary for review.

Step 7

Produce HTML File

Create assessment-src/components/[name].html with all 4 tagged blocks.

Step 8

Build and Verify

Open in browser. Verify sidebar, summary, and content. Commit and push.

node assessment-src/build.js

Output Format

Two deliverables per component: markdown summary (for review) and HTML file (for the report).

Markdown Summary

Use for in-session review before producing the HTML file.

## [Component Name] `nodeId`

**DS Health:** [Keep / Fix / Restructure / Consolidate / Product Layer / Remove]
**Native Status:** [Ready / Needs Refinement / Requires Rework / Not Applicable]

### DS Health
| Trait | Rating | Notes |
| Reusable | Pass/Warn/Fail | [note] |
...

### Native Readiness
| ID | Criterion | Status | Notes |
| C1-C7 | [name] | Pass/Flag/Fail | [note] |

### Action Items
| # | Criterion | Action | Status |

HTML Component File

File naming: lowercase, hyphenated — accordion.html, bottom-sheet.html

Template reference: Use the Accordion component file as a working reference for the full HTML structure including nav, summary card, tabbed assessment/changelog layout, trait cards, resolved lists, and action items.

Key conventions:

Resolved issues — Use resolved-list class instead of individual infobox blocks.

Action items — Show only open items. Omit completed rows.

Section headings — No A./B./C. prefixes. Use plain sub-headings.

Inline styles — Avoid. Use CSS classes instead.

Copy — Keep concise and direct. Apple-style minimalism.

Interaction states — Omit N/A rows. Add a table-footnote if needed.

Assessment Progress

Current Assessments

Component	Node	DS Verdict	Native Status	Status	Notes
Accordion	16870:9288	Fix	Needs Refinement	Re-assessing	Open: C7

Open Issues

Component	Criterion	Action	Status
Accordion	C7	Create native component files and register Code Connect mappings via the Figma Code Connect CLI.	Open

Ownership

Role	Owner
DS debloat audit methodology	DS team lead
Native readiness methodology	Design engineering lead
HTML report & build script	DS team / design engineering
Component HTML files	Produced per-session
Figma file access	Figma admin
Token naming	Design system owner

Mobile Documentation Criteria — 9-Point Assessment

Use this checklist to evaluate every component's documentation before presenting. Score each criterion as Pass, Partial, or Fail. Target: 9/9.

Must-Haves (1–5)

#	Criterion	Pass	Partial	Fail
1	Live preview / playground	Interactive preview with all property controls that update visually	Preview exists but missing controls for some properties	No interactive preview or static screenshot only
2	Native install / import	SPM URL + Gradle dependency + import statements. "Planned API" badge if unpublished	Only one platform shown	No install or import instructions
3	SwiftUI & Compose snippets	All styles have SwiftUI + Compose snippets with Copy button. Component API pattern — not container code	Some styles have snippets, others show placeholders	All blocks show `// Loading...` or container code
4	Props / API table	Prominent table mapping every Figma property → SwiftUI + Compose equivalent	Table exists but buried or incomplete	No mapping table
5	Variants & states (with code)	Every style section in Style tab has SwiftUI/Compose component API snippet	Code tab has snippets but Style tab still shows placeholder text	No code paired with visual variants

Good-to-Haves (6–9)

#	Criterion	Pass	Partial	Fail
6	Native platform notes	Accessibility table with iOS + Android columns (touch targets, focus rings, icon-only labels, destructive role, loading state)	Some notes but not structured or single-platform only	No platform-specific guidance
7	Design token connection	Each style/appearance shows token name + hex value + state. Per-mode color specs documented	Token names visible but hex breakdowns or per-mode specs missing	Only hex values with no token names
8	Changelog / version history	Semantic versioning, entries tied to C1–C7, status badges, Figma node IDs	History exists but no criterion linking	No changelog
9	Figma ↔ code mapping	Property mapping table matches current architecture, suggested file paths shown, Code Connect readiness table present	Mapping exists but references outdated architecture	No Code Connect mapping

Scoring Scale

Score	Rating
9/9	Excellent — exceeds all top DS benchmarks
7–8/9	Strong — on par with Google Material 3
5–6/9	Acceptable — gaps need addressing
3–4/9	Weak — significant documentation gaps
0–2/9	Not ready — fundamental sections missing

Stale Content Check

After any component restructure (variant count change, property renaming, architecture change), verify ALL of these reflect the current architecture:

Verdict summary (variant count, property names)
Interactive playground controls (match current properties)
Style tab per-style code snippets (match current API)
Code tab property mapping table (match current Figma properties)
Code tab usage snippets (match current API)
Criteria Scorecard notes (match current variant count and property names)
Code Connect property mapping (match current architecture)
Variants Inventory table (match current variant count and schema)
Behavior table (match current states and properties)

Workflow

After completing or updating any component documentation, run through all 9 criteria
Score each as Pass / Partial / Fail
Run the Stale Content Check if the component was restructured
Fix any Partial or Fail items before presenting
Report the final score (e.g. "Button: 9/9")