> For the complete documentation index, see [llms.txt](https://docs.devlaunchers.org/dl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devlaunchers.org/dl-docs/universal-design-system/universal-design-system/contributing/creating-components/component-property-+-variable-planning.md).

# 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`)
  * <mark style="color:red;">Style variants (e.g.,</mark> <mark style="color:red;"></mark><mark style="color:red;">`solid`</mark><mark style="color:red;">,</mark> <mark style="color:red;"></mark><mark style="color:red;">`ghost`</mark><mark style="color:red;">,</mark> <mark style="color:red;"></mark><mark style="color:red;">`outlined`</mark><mark style="color:red;">)</mark>
  * 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/*`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devlaunchers.org/dl-docs/universal-design-system/universal-design-system/contributing/creating-components/component-property-+-variable-planning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.