DSDS Purpose Guideline

2 definitions in this file:

useCase
purpose

Describes the scenario. Should be concrete and situation-driven — describe the user's situation, not the artifact's features.

Whether the use case is an example to follow or to avoid.

The recommended alternative artifact for this scenario. Typically provided for whenNotToUse entries to direct the reader toward a more appropriate component, pattern, or token.

References:

richText

[ { "kind": "positive", "description": "When the user needs to commit a destructive or high-stakes action (e.g., Save, Confirm, Delete) and that action is the primary task on the surface." }, { "kind": "positive", "description": "When triggering a state change inside the application — submitting a form, opening a dialog, or moving to the next step of a workflow." }, { "kind": "negative", "description": "When the action navigates the user to a different page or external URL.", "alternative": { "identifier": "link", "rationale": "Links carry semantic meaning for navigation, are crawlable by assistive technology, and respect the user's default browser behavior (open in new tab, copy URL, etc.)." } }, { "kind": "negative", "description": "When the surface needs a long list of inline choices that the user can toggle on and off.", "alternative": { "identifier": "chip", "rationale": "Chips communicate selection and removal affordances. Using a button for each option implies an action rather than a togglable selection." } } ]

Identifies this guideline as a purpose spec.

Scenario-driven guidance describing when this artifact is or is not the right choice.

AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.

References: useCase, agents

{ "kind": "purpose", "useCases": [ { "kind": "positive", "description": "When the user needs to commit a destructive or high-stakes action (e.g., Save, Confirm, Delete) and that action is the primary task on the surface." }, { "kind": "positive", "description": "When triggering a state change inside the application — submitting a form, opening a dialog, or moving to the next step of a workflow." }, { "kind": "negative", "description": "When the action navigates the user to a different page or external URL.", "alternative": { "identifier": "link", "rationale": "Links carry semantic meaning for navigation, are crawlable by assistive technology, and respect the user's default browser behavior (open in new tab, copy URL, etc.)." } } ], "agents": { "intent": "Decide when the button component is the correct choice versus a link, chip, or icon-button.", "disambiguation": [ { "entity": "link", "distinction": "Use a button when the action changes application state. Use a link when the action navigates to a URL." } ], "keywords": [ "when to use", "decision", "purpose", "vs link", "vs chip" ] } }