Component Property + Variable Planning

⚙️ Property & Variable Planning

🔧 What It Is & Why It Matters

Property and Variable Planning is a foundational step in our component creation workflow. It’s the design equivalent of mise en place—a preparation phase that ensures we understand exactly what a component needs before visual design, prototyping, or variant logic begins.

This planning ensures that:

• ✅ We stay consistent across the design system

• ✅ Components scale smoothly with themes, states, and responsiveness

• ✅ Designers and developers align early on structure and logic

• ✅ Tokens and variables are used intentionally—no hardcoding or guesswork

---

📌 What It Includes

At a minimum, this step defines:

• The component’s properties (e.g. size, state, hasIcon, style)

• The variable collections and tokens to use for:

  • Surface (backgrounds)

  • Content (text/icon colors)

  • Border (stroke color and width)

  • Layout (padding, gap, radius)

• Expected variants and interactive states

Property & Variable Planning isn’t just a checklist—it’s how we build themed, scalable, and accessible components that behave consistently across a system.

---

🧩 Initial Planning Questions

🖱️ Will this component have interactive states (hover, focus, active)?

• Yes → Is it a Toggle component? (e.g., switch, pill, checkbox) → Is it a Priority component? (e.g., button, CTA) → Use tokens from the status collections:

  • toggle/surface, toggle/border, toggle/content

  • or priority/surface, priority/content, etc.

• No → Use the semantic collection:

  • semantic/surface, semantic/border, semantic/content

  These reflect static intent (e.g., info, success) without interaction behavior.

---

📏 Will this component support scalable sizes (sm, base, lg)?

• Yes → Use tokens from the size collection:

  • padding/scale/component-name/size

  • gap/component-name/icon-text

  • radius/component-name

• No → Use fixed values (e.g., padding: 8px, gap: 4px) sparingly

  This is acceptable for one-size utility components like badges or indicators.

---

🧩 Will this component include smaller, nested components?

Examples: Icon, Avatar, Badge, Progress Bar, Label

• Yes → Identify and reuse existing subcomponents where possible:

  • 🔁 Can we reuse an existing icon slot or avatar component?

  • 🧠 Will states or size of the parent affect nested components (e.g., icon color or size)? → Document:

    • Expected slots (e.g., icon, dismiss button)

    • Token dependencies between parent and child components

• No → Keep planning scoped to a single-level structure.

Design it once, reuse it often.

---

🎛️ Will this component have variants or toggled options?

This includes anything that toggles visibility, style, or structure.

• Yes → Define:

  • Boolean props (e.g., has-icon, is-expandable)

  • Style variants (e.g., solid, ghost, outlined)

  • Content toggles (e.g., optional icon or expanding content) → Consider how toggles impact:

  • Layout (padding/gap)

  • Visibility logic

  • Token application

• No → Keep configuration minimal—avoid unnecessary complexity.

Variants and toggles are where flexibility meets system discipline—design the edges, but constrain the chaos.

---

📦 Component Example: Pill

Based on discovery, the Pill component:

• Will not have interaction states → use semantic/* tokens

• Will scale by size → use tokens from the size collection

• Has optional icon → needs boolean logic and slot configuration

🧾 Property & Variable Plan: Pill Component

Design Element	Variable Collection	Notes
Surface color	semantic/surface	Background color for pill shape
Content color	semantic/surface	Applied to text and icon
Border color	semantic/surface	Optional; used for outlined/ghost styles
Border radius	rounded/#	Consistent shape across all sizes
Size	default: base	Create a property for scalable size modes
Border width	border-width/#	Defines stroke thickness
Padding	padding/#	Vertical/horizontal spacing by size
Gap	gap/#	Spacing between icon and text
Boolean	has-icon	Used to toggle icon slot visibility
Style	default: grey	Style variants: solid, outlined, ghost
Text	Tag Text	Create string property to change label text

---

✅ Pill Summary

• ✔️ No interaction → uses semantic tokens

• ✔️ Scales → uses size tokens for padding/gap/radius

• ✔️ Variant support → style (solid/ghost) and has-icon boolean

• ✔️ Modular → icon slot inherits token logic from content/*