From d2e4e5cb8b5a342007a861635ed7891af5eb1bec Mon Sep 17 00:00:00 2001 From: xkxx Date: Fri, 10 Apr 2026 17:09:16 -0700 Subject: [PATCH] docs: move spec.md to docs and streamline --- spec.md => docs/spec.md | 120 +++++----------------------------------- 1 file changed, 15 insertions(+), 105 deletions(-) rename spec.md => docs/spec.md (69%) diff --git a/spec.md b/docs/spec.md similarity index 69% rename from spec.md rename to docs/spec.md index 94a3b6a4..d241725b 100644 --- a/spec.md +++ b/docs/spec.md @@ -14,10 +14,9 @@ describe design tokens is loosely based on the As such, it's easily converted from / to tokens.json, Figma variables, and Tailwind theme configs. -The yaml may be embedded into DESIGN.md as Front Matter, or be distributed -throughout the document as YAML code blocks. +The yaml may be embedded into DESIGN.md as Front Matter. -Front Matter Example: +Example: ```yaml --- @@ -35,38 +34,7 @@ typography: --- ``` -YAML codeblock example:[^2] - -```markdown -## Colors - -‍```yaml -colors: - primary: "#647D66" -‍``` - -The palette uses a deep "Evergreen" primary to establish authority and -health-sector credibility. Use for moments of highest authority and deep -contrast. - -## Typography - -‍```yaml -typography: - headline-lg: - fontFamily: Google Sans Display - fontSize: 42px - fontWeight: 500 - lineHeight: 50px - letterSpacing: 1.2px -‍``` - -This design system utilizes a dual-font strategy to balance character with -functionality. **Google Sans Display** provides a friendly, slightly rounded -geometric feel for headlines. -``` - -### Schema +## Schema Here's the overall schema for the design tokens: @@ -111,7 +79,9 @@ contain an object path to another value in the YAML tree. The referenced object must be a primitive value, e.g. colors.primary-60, rather than an object, e.g. colors. -# File Format +# Sections + +Every `DESIGN.md` follows the same structure. Sections can be omitted if they’re not relevant to your project, but the order should be preserved. ## Overview @@ -317,7 +287,7 @@ variants and make the appropriate styling decisions. ### Component Property Tokens -A component may have these sub tokens: +Each component has a set of properties that are themselves design tokens: - backgroundColor: \ - textColor: \ @@ -327,73 +297,13 @@ A component may have these sub tokens: ## Do's and Don'ts -# Use Cases - -## Usage within Stitch - -DESIGN.md allows the user to gain insight into how Stitch understands their -design request and enables Stitch agent and the user to collaborate on the -design system. - -- **Enforcing Style:** The agent consumes the DESIGN.md to enforce systemic - rules, generating UI code that strictly adheres to the included design tokens - and guidelines. -- **Enhancing Consistency:** The file is used to enhance the prompt for - generating and editing existing screens to ensure consistency across the - project. -- **Decoupling Content and Style:** Stitch is designed to strictly decouple - content from styling. The DESIGN.md provides the styling rulebook, which the - agent combines with the context of previous screens to determine the actual - content, preventing the model from inserting irrelevant content (like a map in - a non-dog-walking app) based only on the design system contents. - -## Usage outside of Stitch - -We also envision usage of the DESIGN.md file in the broader design industry: - -- **Viewing the System:** Users can view the generated design.md file. They can - also view the design system of a selected screen in the UI panel (renamed from - "theme" to "Design System" panel). -- **Setting Defaults:** Users can select an available design system to be used by - default for all future generations within the same project. -- **Refinement:** The generated DESIGN.md can be used to enhance prompts, - allowing users to guide the agent toward greater consistency and adherence to - the defined look and feel. -- **Editing:** Users can make simple edits to the design system via the Design - System panel in the UI. -- **Export:** When a user exports a project, the design.md file is intended to be - included in the exported zip file. - -# Creation - -### Agent Generation - -1. The agent interprets high-level aesthetic prompts from the user (e.g., - "playful and accessible"). -2. The agent generates a valid design token specification and style guidelines - from scratch, which is then summarized in the markdown format. -3. Agent creates a DESIGN.md file based on the design tokens and a DESIGN.md - template. +Practical guidelines and common pitfalls. These act as guardrails when creating designs. -### Direct Input - -Advanced users may manually define or directly edit the design system. This -includes defining custom design personas and encoding detailed design -preferences to precisely guide the Stitch agent's UI generation. - -### Derived from Branding Materials - -The design system can be generated from external assets. The agent extracts -style and token information from sources such as user-provided images or a -specified URL containing branding profiles and design elements to create the -initial DESIGN.md file. - -A DESIGN.md file has two faces: - -- The prose describes the design system. -- The structured design tokens. - ---- +```markdown +## Do's and Don'ts -[^1]: May add tokens for border or box shadow later. -[^2]: Provincial format, exploring results. +- Do use the primary color only for the single most important action per screen +- Don't mix rounded and sharp corners in the same view +- Do maintain WCAG AA contrast ratios (4.5:1 for normal text) +- Don't use more than two font weights on a single screen +```