From 98482e15d73074768578d48ceb5ce4acedf297e0 Mon Sep 17 00:00:00 2001 From: samcartersmith Date: Wed, 22 Apr 2026 16:54:02 -0700 Subject: [PATCH 1/3] Update SKILL.md changing cbhq to coinbase.com --- skills/cds-accessibility/SKILL.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/skills/cds-accessibility/SKILL.md b/skills/cds-accessibility/SKILL.md index c0f2ce9c8a..f5d8b99e58 100644 --- a/skills/cds-accessibility/SKILL.md +++ b/skills/cds-accessibility/SKILL.md @@ -8,7 +8,7 @@ description: | technology behavior, and verifying usage against official CDS documentation—not generic web ARIA tutorials. Use this skill when implementing or reviewing CDS UI for screen reader, keyboard, and labeled control requirements. Ground in current CDS component docs per the cds-docs skill (MCP or curl; see skill body)—and - [https://cds.cbhq.net/](https://cds.cbhq.net/) for human-readable browsing when helpful. + [https://cds.coinbase.com/](https://cds.coinbase.com/) for human-readable browsing when helpful. license: Apache-2.0 metadata: author: [design-system@coinbase.com](mailto:design-system@coinbase.com) @@ -31,8 +31,8 @@ Use this skill to **consume CDS components accessibly**: apply **documented** pr ## Prerequisites -- **cds-docs (required):** You can follow [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) to load **current** official CDS component documentation. Choose **web** or **mobile**, start from the **route index** (`list-cds-routes` with MCP, or the same index via `curl` to `https://cds.coinbase.com/llms/{web|mobile}/routes.txt`), then fetch the `.txt` pages you need for props and a11y examples. **CDS MCP** with `get-cds-doc` / `list-cds-routes` is the **preferred first step** when available (same as **`cds-code`**). **If MCP is unavailable or errors,** use **`curl -fsSL`**, per cds-docs, against `https://cds.coinbase.com/llms/`, where `` comes from the index. -- **cds.cbhq.net (recommended):** [cds.cbhq.net](https://cds.cbhq.net/) for browsing and deep links when you need **human** context alongside the `llms` / MCP sources. +- **cds-docs (required):** You can follow [**cds-docs**](https://skills..net/skill/frontend/cds-public/cds-docs) to load **current** official CDS component documentation. Choose **web** or **mobile**, start from the **route index** (`list-cds-routes` with MCP, or the same index via `curl` to `https://cds.coinbase.com/llms/{web|mobile}/routes.txt`), then fetch the `.txt` pages you need for props and a11y examples. **CDS MCP** with `get-cds-doc` / `list-cds-routes` is the **preferred first step** when available (same as **`cds-code`**). **If MCP is unavailable or errors,** use **`curl -fsSL`**, per cds-docs, against `https://cds.coinbase.com/llms/`, where `` comes from the index. +- **cds.coinbase.com (recommended):** [cds.coinbase.com](https://cds.coinbase.com/) for browsing and deep links when you need **human** context alongside the `llms` / MCP sources. - For full CDS UI build steps (package discovery, styling, theming, visual check), use the **`cds-code`** skill; run its session setup when you are also building or refactoring screens. ## Success criteria @@ -44,8 +44,8 @@ For a given change, **this skill is complete** when all three dimensions below a - Every **interactive** or **name-bearing** CDS control in the change has props set **as required or recommended** in the current **official CDS component doc** (per **cds-docs** and **`get-cds-doc`** or the equivalent `curl` fetch) for that **platform** (do not mix **web** and **React Native** patterns). - **Form, validation, errors, and live regions** follow the **documented** association and feedback patterns for the CDS form components in use, not a generic or off-repo pattern. - **Icons, images, and media** follow CDS doc guidance for **decorative vs meaningful** content and any `alt` / `accessibilityLabel` (or equivalent) requirements. -- If the change includes a **focus-managed** CDS component (see **Part 1, Step 5**; examples: **Modal**, **Tray**, **Tooltip**, or any component whose doc defines focus APIs), **open/close/Tab/restore** behavior matches the **official** **CDS** doc (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)) and any examples you used (e.g. [Modal](https://cds.cbhq.net/components/overlay/Modal/)); if there are no such components, this bullet does not apply. -- If the change includes **CDS `Text`** (or equivalent typography) for **titles, headings, or body/label copy**, **`as` (web)** and **`accessibilityRole` (RN)** match **content intent** and the [Text (typography) doc](https://cds.cbhq.net/components/typography/Text/); do **not** use **heading** semantics on **non-heading** `font` styles when that would **misrepresent** structure (per the **Text** web/mobile doc from **cds-docs**). If `Text` is not in the change, this bullet does not apply. +- If the change includes a **focus-managed** CDS component (see **Part 1, Step 5**; examples: **Modal**, **Tray**, **Tooltip**, or any component whose doc defines focus APIs), **open/close/Tab/restore** behavior matches the **official** **CDS** doc (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)) and any examples you used (e.g. [Modal](https://cds.coinbase.com/components/overlay/Modal/)); if there are no such components, this bullet does not apply. +- If the change includes **CDS `Text`** (or equivalent typography) for **titles, headings, or body/label copy**, **`as` (web)** and **`accessibilityRole` (RN)** match **content intent** and the [Text (typography) doc](https://cds.coinbase.com/components/typography/Text/); do **not** use **heading** semantics on **non-heading** `font` styles when that would **misrepresent** structure (per the **Text** web/mobile doc from **cds-docs**). If `Text` is not in the change, this bullet does not apply. ### 2. Component selection (confident and documented) @@ -55,7 +55,7 @@ For a given change, **this skill is complete** when all three dimensions below a ### 3. Documentation engagement (read and applied) -- For **each** CDS component in the change, **current** official documentation was loaded **per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)**: **prefer** **`list-cds-routes`** and **`get-cds-doc`** (CDS MCP) when available; if MCP is unavailable or fails, use **`curl -fsSL`** to `https://cds.coinbase.com/llms/...` from the route index, per cds-docs. Include **cross-linked** routes the doc points to (e.g. `FormField`, `Modal` composition) when they affect your feature. Use [cds.cbhq.net](https://cds.cbhq.net/) for extra context when needed. +- For **each** CDS component in the change, **current** official documentation was loaded **per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)**: **prefer** **`list-cds-routes`** and **`get-cds-doc`** (CDS MCP) when available; if MCP is unavailable or fails, use **`curl -fsSL`** to `https://cds.coinbase.com/llms/...` from the route index, per cds-docs. Include **cross-linked** routes the doc points to (e.g. `FormField`, `Modal` composition) when they affect your feature. Use [cds.cbhq.net](https://cds.coinbase.com/) for extra context when needed. - The implementation is explainable in terms of **specific** doc material—prop table, examples, a11y or platform notes—not only “it looks right” visually. - If the doc or your team’s process requires a **device or manual** check (e.g. VoiceOver, TalkBack), that expectation is **acknowledged** as satisfied, or **explicitly** still pending with a clear reason. @@ -198,7 +198,7 @@ These patterns are **not** a substitute for reading each component’s doc. They ### CDS resources -- **Site:** [cds.cbhq.net](https://cds.cbhq.net/) for browsing and deep links alongside [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) and the **`llms`** fetches. +- **Site:** [cds.cbhq.net](https://cds.coinbase.com/) for browsing and deep links alongside [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) and the **`llms`** fetches. - **Text (typography):** [cds.cbhq.net/components/typography/Text/](https://cds.cbhq.net/components/typography/Text/) (**`as`**, `font`, heading semantics on web; **`accessibilityRole`** on React Native per the **Text** **web** and **mobile** **official** docs in [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs).) - **cds-docs (how to load CDS .txt for any component, including a11y):** Follow [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs). **Order:** (1) **CDS MCP**—`list-cds-routes` with `platform: "web" | "mobile"`, then **`get-cds-doc`** with a route from the index (case-sensitive, paths end in **.txt**). (2) If MCP is not configured, fails, or returns errors, **`curl -fsSL 'https://cds.coinbase.com/llms/'`**: start from the [web](https://cds.coinbase.com/llms/web/routes.txt) or [mobile](https://cds.coinbase.com/llms/mobile/routes.txt) index; **map component → route** from the index only, then fetch the pages you need. Whether you use **MCP** or **`curl`** is an implementation detail (see cds-docs). @@ -231,4 +231,4 @@ These patterns are **not** a substitute for reading each component’s doc. They ### Where this skill stops -If the **official** **CDS** doc (from **cds-docs** via **`get-cds-doc`** or **`curl`**) does not document a behavior you need, **do not** fabricate a full custom accessibility architecture inside this skill’s name—record the gap, use **design/DS** follow-up, or **external** accessibility guidance for non-CDS layers. \ No newline at end of file +If the **official** **CDS** doc (from **cds-docs** via **`get-cds-doc`** or **`curl`**) does not document a behavior you need, **do not** fabricate a full custom accessibility architecture inside this skill’s name—record the gap, use **design/DS** follow-up, or **external** accessibility guidance for non-CDS layers. From 143cfe3e9018812a12ff43504d28feb8886e3b3d Mon Sep 17 00:00:00 2001 From: samcartersmith Date: Wed, 22 Apr 2026 16:56:43 -0700 Subject: [PATCH 2/3] Update README.md --- skills/cds-accessibility/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/cds-accessibility/README.md b/skills/cds-accessibility/README.md index 6508c8b1bd..2ee5b51766 100644 --- a/skills/cds-accessibility/README.md +++ b/skills/cds-accessibility/README.md @@ -1,6 +1,6 @@ # cds-accessibility -Teaches your AI agent to use **Coinbase Design System (CDS)** components in an **accessible** way: **documented** props (for example `accessibilityLabel` and `accessibilityState` on React Native, and `aria-*` / `as` / `role` patterns on web **as the CDS web API supports**), and **choosing CDS components** whose official docs cover the right assistive-technology behavior. Grounding is [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) (prefer **CDS MCP** `list-cds-routes` / `get-cds-doc` when available; if MCP is unavailable or fails, use **`curl`** to `https://cds.coinbase.com/llms/...` per cds-docs) and [cds.cbhq.net](https://cds.cbhq.net/)—not a generic ARIA or WCAG tutorial that ignores CDS. +Teaches your AI agent to use **Coinbase Design System (CDS)** components in an **accessible** way: **documented** props (for example `accessibilityLabel` and `accessibilityState` on React Native, and `aria-*` / `as` / `role` patterns on web **as the CDS web API supports**), and **choosing CDS components** whose official docs cover the right assistive-technology behavior. Grounding is [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) (prefer **CDS MCP** `list-cds-routes` / `get-cds-doc` when available; if MCP is unavailable or fails, use **`curl`** to `https://cds.coinbase.com/llms/...` per cds-docs) and [cds.coinbase.com](https://cds.coinbase.com/)—not a generic ARIA or WCAG tutorial that ignores CDS. ## What it does @@ -55,4 +55,4 @@ Install via your organization’s skill registry. To add **cds-docs** in the sam - [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) – how to load CDS **.txt** (MCP and curl). - **`cds-code`** in the same registry – CDS-first **building** and **visual** verification. -- [https://cds.cbhq.net/](https://cds.cbhq.net/) – official CDS documentation. +- [https://cds.coinbase.com/](https://cds.coinbase.com/) – official CDS documentation. From 9a5f00de8b819faae14d6fc4f1147b68c0f52640 Mon Sep 17 00:00:00 2001 From: Sam Smith Date: Thu, 23 Apr 2026 09:38:54 -0700 Subject: [PATCH 3/3] Remove hardcoded URLs from cds-accessibility skill Replace all cds.coinbase.com, cds.cbhq.net, and skills.cbhq.net links with plain prose or **cds-docs** references so the skill has no hardcoded URLs (except the shell install command, which is now also removed in favour of pointing users to cds-docs). Bump version to 1.0.4. Made-with: Cursor --- README.md | 12 ++--- skills/cds-accessibility/README.md | 33 ++++++------ skills/cds-accessibility/SKILL.md | 86 +++++++++++++++--------------- 3 files changed, 62 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 711120a365..cbcf3068d4 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,8 @@ # Coinbase Design System -

- Coinbase Design System -

- Welcome to the Coinbase Design System (CDS)! -Please visit our website https://cds.coinbase.com for the latest documentation. +Please visit our website [https://cds.coinbase.com](https://cds.coinbase.com) for the latest documentation. ## Setup @@ -17,7 +13,7 @@ git clone git@github.com:coinbase/cds.git cd cds ``` -2. **Use the correct Node.js version** +1. **Use the correct Node.js version** We suggest [nvm](https://github.com/nvm-sh/nvm/tree/master) to manage Node.js versions. If you have it installed, you can use these commands to set our current Node.js version. @@ -27,7 +23,7 @@ nvm use corepack enable ``` -3. **Install dependencies** +1. **Install dependencies** ```sh yarn install @@ -65,4 +61,4 @@ For information about reporting security vulnerabilities, please see our [Securi ## License -This project is licensed under the terms described in [LICENSE](LICENSE). +This project is licensed under the terms described in [LICENSE](LICENSE). \ No newline at end of file diff --git a/skills/cds-accessibility/README.md b/skills/cds-accessibility/README.md index 2ee5b51766..80053edc7e 100644 --- a/skills/cds-accessibility/README.md +++ b/skills/cds-accessibility/README.md @@ -1,32 +1,31 @@ # cds-accessibility -Teaches your AI agent to use **Coinbase Design System (CDS)** components in an **accessible** way: **documented** props (for example `accessibilityLabel` and `accessibilityState` on React Native, and `aria-*` / `as` / `role` patterns on web **as the CDS web API supports**), and **choosing CDS components** whose official docs cover the right assistive-technology behavior. Grounding is [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) (prefer **CDS MCP** `list-cds-routes` / `get-cds-doc` when available; if MCP is unavailable or fails, use **`curl`** to `https://cds.coinbase.com/llms/...` per cds-docs) and [cds.coinbase.com](https://cds.coinbase.com/)—not a generic ARIA or WCAG tutorial that ignores CDS. +Teaches your AI agent to use **Coinbase Design System (CDS)** components in an **accessible** way: **documented** props (for example `accessibilityLabel` and `accessibilityState` on React Native, and `aria-*` / `as` / `role` patterns on web **as the CDS web API supports**), and **choosing CDS components** whose official docs cover the right assistive-technology behavior. Grounding is **cds-docs** (prefer **CDS MCP** `list-cds-routes` / `get-cds-doc` when available; if MCP is unavailable or fails, fall back per **cds-docs**) and the CDS documentation site—not a generic ARIA or WCAG tutorial that ignores CDS. ## What it does -- **Doc-first consumption** – For each CDS component in scope, follow [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) to load the **.txt** for **prop tables** and **examples** (MCP or curl; same content). +- **Doc-first consumption** – For each CDS component in scope, follow **cds-docs** to load the **.txt** for **prop tables** and **examples** (MCP or curl; same content). - **React Native** – Apply `accessibilityLabel`, `accessibilityHint`, `accessibilityState`, `accessibilityRole`, and any CDS-documented props **where the component or scenario requires them**. -- **Web** – Wire labels, `aria-*`, `as`, and `role` **through the CDS web component’s** supported API, following official examples. +- **Web** – Wire labels, `aria-*`, `as`, and `role` **through the CDS web component's** supported API, following official examples. - **Component choice** – Prefer CDS **composites** (modals, forms, lists, etc.) when their **docs** describe the **focus, keyboard, and semantics** you need, instead of re-building from layout primitives. - **Focus management (scoped)** – When the change uses **focus-managed** CDS components (e.g. **Modal**, **Tray**, **Tooltip**, or others whose **official** doc defines focus), follow **Part 1, Step 5** in `SKILL.md` and the official examples—not generic focus-trap guidance for all UI. - **Definition of done** – Work is **complete** when it satisfies **Success criteria** in `SKILL.md` (doc-correct CDS a11y **props**, **confident** component choice from the **current** **CDS** **.txt** per **cds-docs**, and all relevant **docs** read and applied—including cross-links). -- **Text (typography) and headings** – Match **`as`** (web) and **`accessibilityRole`** (React Native) to content intent and the [Text (typography)](https://cds.cbhq.net/components/typography/Text/) doc; use **Text** **web** and **mobile** routes per **cds-docs**. -- **Relationship to `cds-code`** – **`cds-code`** covers building CDS UI (layout, theming, imports, visualization, **visual** verification). **This skill** covers **CDS accessibility consumption** and **a11y-driven** component choice. Use both for typical feature work; use [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) for how you fetch **CDS** **.txt** for both. +- **Text (typography) and headings** – Match **`as`** (web) and **`accessibilityRole`** (React Native) to content intent and the Text (typography) doc; use **Text** **web** and **mobile** routes per **cds-docs**. +- **Relationship to `cds-code`** – **`cds-code`** covers building CDS UI (layout, theming, imports, visualization, **visual** verification). **This skill** covers **CDS accessibility consumption** and **a11y-driven** component choice. Use both for typical feature work; use **cds-docs** for how you fetch **CDS** **.txt** for both. ## Dependencies - -| Dependency | Required | Purpose | -| ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| **cds-docs** | Yes | [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs): how to load official CDS **.txt** (index first, then pages)—**MCP** (`list-cds-routes`, `get-cds-doc`) when available, else **`curl -fsSL`** to `https://cds.coinbase.com/llms/...`. | -| **CDS MCP server** | Optional | **Preferred** first step in cds-docs when the environment has CDS MCP; not required if you use the **curl** path from cds-docs. | -| **cds.cbhq.net** | Recommended | Browsing and shared links; same content family as the **`llms`** / MCP **.txt** sources. | -| **cds-code skill** | Recommended | Session setup, package discovery, and CDS-first UI build flow when you are not doing a read-only a11y review. | +| Dependency | Required | Purpose | +| ------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| **cds-docs** | Yes | **cds-docs**: how to load official CDS doc content (index first, then pages)—MCP when available, else curl per cds-docs. | +| **CDS MCP server** | Optional | **Preferred** first step in cds-docs when the environment has CDS MCP; not required if you use the **curl** path from cds-docs. | +| **CDS documentation site** | Recommended | Browsing and shared links; same content family as the **`llms`** / MCP **.txt** sources. | +| **cds-code skill** | Recommended | Session setup, package discovery, and CDS-first UI build flow when you are not doing a read-only a11y review. | ### Documentation access (cds-docs, not MCP-only) -**Do not** treat CDS MCP as mandatory. For **tool order**, **indices**, and **`curl` URLs**, follow [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) (MCP first when it works; otherwise `curl` to the Coinbase `llms` host per that skill). Optional MCP install and editor wiring are covered in the [CDS AI overview](https://cds.coinbase.com/getting-started/ai-overview#first-time-setup) and cds-docs, not duplicated here. +**Do not** treat CDS MCP as mandatory. For **tool order**, **indices**, and **`curl` URLs**, follow **cds-docs** (MCP first when it works; otherwise `curl` to the Coinbase `llms` host per that skill). Optional MCP install and editor wiring are covered in the CDS AI overview and **cds-docs**, not duplicated here. ## Included scripts @@ -34,9 +33,7 @@ This skill does **not** ship a script. Optional automation (for example a repo-l ## Installing this skill -Install via your organization’s skill registry. To add **cds-docs** in the same flow your org uses: - -`npx @cbhq/cb-skills add https://skills.cbhq.net --skill frontend/cds-public/cds-docs` (see **cds-docs** for the exact command and registry URL). +Install via your organization's skill registry. See **cds-docs** for the install command and registry URL. ## When to use @@ -53,6 +50,6 @@ Install via your organization’s skill registry. To add **cds-docs** in the sam ## See also -- [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) – how to load CDS **.txt** (MCP and curl). +- **cds-docs** – how to load CDS **.txt** (MCP and curl). - **`cds-code`** in the same registry – CDS-first **building** and **visual** verification. -- [https://cds.coinbase.com/](https://cds.coinbase.com/) – official CDS documentation. +- The CDS documentation site – official CDS documentation. diff --git a/skills/cds-accessibility/SKILL.md b/skills/cds-accessibility/SKILL.md index f5d8b99e58..d655b2e20e 100644 --- a/skills/cds-accessibility/SKILL.md +++ b/skills/cds-accessibility/SKILL.md @@ -8,31 +8,31 @@ description: | technology behavior, and verifying usage against official CDS documentation—not generic web ARIA tutorials. Use this skill when implementing or reviewing CDS UI for screen reader, keyboard, and labeled control requirements. Ground in current CDS component docs per the cds-docs skill (MCP or curl; see skill body)—and - [https://cds.coinbase.com/](https://cds.coinbase.com/) for human-readable browsing when helpful. + the CDS documentation site for human-readable browsing when helpful. license: Apache-2.0 metadata: - author: [design-system@coinbase.com](mailto:design-system@coinbase.com) - version: "1.0.3" + author: design-system@coinbase.com + version: "1.0.4" --- # cds-accessibility -Use this skill to **consume CDS components accessibly**: apply **documented** props and patterns from CDS, and **choose CDS components** whose official docs describe the interaction you need. Do **not** use this file as a generic WCAG or ARIA handbook. **When in doubt,** follow [**cds-docs**](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) to load **current** CDS component documentation. **Prefer** the **CDS MCP** tools `list-cds-routes` and `get-cds-doc` when the MCP is available; **if MCP is not configured, fails, or returns errors,** use **`curl -fsSL`** to `https://cds.coinbase.com/llms/...` per cds-docs (start from the [web](https://cds.coinbase.com/llms/web/routes.txt) or [mobile](https://cds.coinbase.com/llms/mobile/routes.txt) route index, then fetch only the pages you need; routes are case-sensitive). [cds.cbhq.net](https://cds.cbhq.net/) is an optional **human** companion. Do **not** guess `aria-*` or RN prop names from third-party blogs. +Use this skill to **consume CDS components accessibly**: apply **documented** props and patterns from CDS, and **choose CDS components** whose official docs describe the interaction you need. Do **not** use this file as a generic WCAG or ARIA handbook. **When in doubt,** follow **cds-docs** to load **current** CDS component documentation. **Prefer** the **CDS MCP** tools `list-cds-routes` and `get-cds-doc` when the MCP is available; **if MCP is not configured, fails, or returns errors,** fall back per **cds-docs** (which defines the curl path and index URLs for web and mobile). The CDS documentation site is an optional **human** companion. Do **not** guess `aria-*` or RN prop names from third-party blogs. ## When to use - Use when you implement, extend, or review **CDS** UI and need **names, state, roles, or announcements** to match what CDS supports. - Use when you must set **React Native** accessibility props (`accessibilityLabel`, `accessibilityHint`, `accessibilityState`, `accessibilityRole`, and any CDS-specific props) per component docs. - Use when you must wire **web** CDS components using **`aria-*`**, `as`, `role`, labels, and field patterns **as the CDS web component API exposes** in the doc. -- Use when you must **pick between two CDS options** and accessibility behavior (focus, dialog behavior, list semantics) should drive the choice—read which component’s doc matches the task. +- Use when you must **pick between two CDS options** and accessibility behavior (focus, dialog behavior, list semantics) should drive the choice—read which component's doc matches the task. - Use alongside **`cds-code`**: that skill covers building CDS layout, tokens, and imports; this skill covers **CDS accessibility consumption** and **CDS-appropriate** component choice for a11y. - Do not use as the only reference for **non-CDS** pages with no design-system components. Do not replace the **official CDS component doc** (per **cds-docs**) with guessed prop names or third-party blog patterns. ## Prerequisites -- **cds-docs (required):** You can follow [**cds-docs**](https://skills..net/skill/frontend/cds-public/cds-docs) to load **current** official CDS component documentation. Choose **web** or **mobile**, start from the **route index** (`list-cds-routes` with MCP, or the same index via `curl` to `https://cds.coinbase.com/llms/{web|mobile}/routes.txt`), then fetch the `.txt` pages you need for props and a11y examples. **CDS MCP** with `get-cds-doc` / `list-cds-routes` is the **preferred first step** when available (same as **`cds-code`**). **If MCP is unavailable or errors,** use **`curl -fsSL`**, per cds-docs, against `https://cds.coinbase.com/llms/`, where `` comes from the index. -- **cds.coinbase.com (recommended):** [cds.coinbase.com](https://cds.coinbase.com/) for browsing and deep links when you need **human** context alongside the `llms` / MCP sources. +- **cds-docs (required):** You can follow **cds-docs** to load **current** official CDS component documentation. Choose **web** or **mobile**, start from the **route index** (`list-cds-routes` with MCP, or the web or mobile route index per **cds-docs**), then fetch the `.txt` pages you need for props and a11y examples. **CDS MCP** with `get-cds-doc` / `list-cds-routes` is the **preferred first step** when available (same as **`cds-code`**). **If MCP is unavailable or errors,** use **`curl -fsSL`** per **cds-docs** against the route from the index. +- **CDS documentation site (recommended):** the official CDS site for browsing and deep links when you need **human** context alongside MCP sources. - For full CDS UI build steps (package discovery, styling, theming, visual check), use the **`cds-code`** skill; run its session setup when you are also building or refactoring screens. ## Success criteria @@ -44,8 +44,8 @@ For a given change, **this skill is complete** when all three dimensions below a - Every **interactive** or **name-bearing** CDS control in the change has props set **as required or recommended** in the current **official CDS component doc** (per **cds-docs** and **`get-cds-doc`** or the equivalent `curl` fetch) for that **platform** (do not mix **web** and **React Native** patterns). - **Form, validation, errors, and live regions** follow the **documented** association and feedback patterns for the CDS form components in use, not a generic or off-repo pattern. - **Icons, images, and media** follow CDS doc guidance for **decorative vs meaningful** content and any `alt` / `accessibilityLabel` (or equivalent) requirements. -- If the change includes a **focus-managed** CDS component (see **Part 1, Step 5**; examples: **Modal**, **Tray**, **Tooltip**, or any component whose doc defines focus APIs), **open/close/Tab/restore** behavior matches the **official** **CDS** doc (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)) and any examples you used (e.g. [Modal](https://cds.coinbase.com/components/overlay/Modal/)); if there are no such components, this bullet does not apply. -- If the change includes **CDS `Text`** (or equivalent typography) for **titles, headings, or body/label copy**, **`as` (web)** and **`accessibilityRole` (RN)** match **content intent** and the [Text (typography) doc](https://cds.coinbase.com/components/typography/Text/); do **not** use **heading** semantics on **non-heading** `font` styles when that would **misrepresent** structure (per the **Text** web/mobile doc from **cds-docs**). If `Text` is not in the change, this bullet does not apply. +- If the change includes a **focus-managed** CDS component (see **Part 1, Step 5**; examples: **Modal**, **Tray**, **Tooltip**, or any component whose doc defines focus APIs), **open/close/Tab/restore** behavior matches the **official** **CDS** doc (per **cds-docs**) and any examples you used (e.g. the Modal overlay); if there are no such components, this bullet does not apply. +- If the change includes **CDS `Text`** (or equivalent typography) for **titles, headings, or body/label copy**, **`as` (web)** and **`accessibilityRole` (RN)** match **content intent** and the Text (typography) doc; do **not** use **heading** semantics on **non-heading** `font` styles when that would **misrepresent** structure (per the **Text** web/mobile doc from **cds-docs**). If `Text` is not in the change, this bullet does not apply. ### 2. Component selection (confident and documented) @@ -55,9 +55,9 @@ For a given change, **this skill is complete** when all three dimensions below a ### 3. Documentation engagement (read and applied) -- For **each** CDS component in the change, **current** official documentation was loaded **per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)**: **prefer** **`list-cds-routes`** and **`get-cds-doc`** (CDS MCP) when available; if MCP is unavailable or fails, use **`curl -fsSL`** to `https://cds.coinbase.com/llms/...` from the route index, per cds-docs. Include **cross-linked** routes the doc points to (e.g. `FormField`, `Modal` composition) when they affect your feature. Use [cds.cbhq.net](https://cds.coinbase.com/) for extra context when needed. -- The implementation is explainable in terms of **specific** doc material—prop table, examples, a11y or platform notes—not only “it looks right” visually. -- If the doc or your team’s process requires a **device or manual** check (e.g. VoiceOver, TalkBack), that expectation is **acknowledged** as satisfied, or **explicitly** still pending with a clear reason. +- For **each** CDS component in the change, **current** official documentation was loaded **per **cds-docs****: **prefer** **`list-cds-routes`** and **`get-cds-doc`** (CDS MCP) when available; if MCP is unavailable or fails, use the curl path per **cds-docs**. Include **cross-linked** routes the doc points to (e.g. `FormField`, `Modal` composition) when they affect your feature. Use the CDS documentation site for extra context when needed. +- The implementation is explainable in terms of **specific** doc material—prop table, examples, a11y or platform notes—not only "it looks right" visually. +- If the doc or your team's process requires a **device or manual** check (e.g. VoiceOver, TalkBack), that expectation is **acknowledged** as satisfied, or **explicitly** still pending with a clear reason. | Dimension | The skill is complete when | @@ -75,14 +75,14 @@ Follow these steps **in order** when accessibility of **CDS** components is in s ### Setup (align with `cds-code` and **cds-docs**) -1. If you are building or editing UI (not a doc-only review), use **`cds-code`** setup: discover packages, align **web** or **mobile**, and use **cds-docs** to read the same foundation **CDS** doc entries that `cds-code` uses for styling/theming (`list-cds-routes` + **`get-cds-doc`** on MCP, or the route index + **`curl`**, per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)). That keeps **platform and routes** consistent. +1. If you are building or editing UI (not a doc-only review), use **`cds-code`** setup: discover packages, align **web** or **mobile**, and use **cds-docs** to read the same foundation **CDS** doc entries that `cds-code` uses for styling/theming (`list-cds-routes` + **`get-cds-doc`** on MCP, or the route index + **`curl`**, per **cds-docs**). That keeps **platform and routes** consistent. 2. For this skill, in addition, for **each CDS component** you will touch, plan to load its doc the same way (MCP or curl) with emphasis on **accessibility**, **props tables**, and **examples**. You do not need to repeat full setup for every small edit; repeat when **runtime, route list, or major CDS version** might have changed. ### Step 1: Scope the CDS surface -1. State whether the work is **web** or **React Native** (or both). Use the **web** or **mobile** **route index** (from **`list-cds-routes`** or `curl` to `.../llms/{web|mobile}/routes.txt`, per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)) for that runtime. +1. State whether the work is **web** or **React Native** (or both). Use the **web** or **mobile** **route index** (from **`list-cds-routes`** or the routes index per **cds-docs**) for that runtime. 2. **List CDS components** in the change. Ignore arbitrary raw HTML unless a CDS pattern in the docs maps to it. 3. If a feature could use a **higher-level CDS component** (modal, list, form field) versus composing only `Box`/`View`, note it—you will compare docs in Step 3. @@ -90,9 +90,9 @@ You do not need to repeat full setup for every small edit; repeat when **runtime For each component in the list: -1. Find its **route** in the index from **Step 1** (MCP: `list-cds-routes`; or **`curl`**, per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)). Paths are **case-sensitive** and must come from the index. -2. **Fetch the doc** for that component: on MCP, **`get-cds-doc`**; otherwise **`curl -fsSL 'https://cds.coinbase.com/llms/'`**. Also fetch any **sub-routes** the doc **cross-links** (e.g. usage with `FormField` or `Modal`). -3. **Throughout this file,** the phrase **`get-cds-doc`** (or the **.txt** from **`curl`**) is the same **source material**; whether you use MCP or curl is an **implementation detail** (see [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)). Read the **prop table** and any **Accessibility**, **ARIA**, **Screen reader**, or **React Native** notes. Treat **required** or **strongly recommended** label/name props as mandatory for the scenarios the doc describes. +1. Find its **route** in the index from **Step 1** (MCP: `list-cds-routes`; or **`curl`**, per **cds-docs**). Paths are **case-sensitive** and must come from the index. +2. **Fetch the doc** for that component: on MCP, **`get-cds-doc`**; otherwise **`curl`** per **cds-docs**. Also fetch any **sub-routes** the doc **cross-links** (e.g. usage with `FormField` or `Modal`). +3. **Throughout this file,** the phrase **`get-cds-doc`** (or the **.txt** from **`curl`**) is the same **source material**; whether you use MCP or curl is an **implementation detail** (see **cds-docs**). Read the **prop table** and any **Accessibility**, **ARIA**, **Screen reader**, or **React Native** notes. Treat **required** or **strongly recommended** label/name props as mandatory for the scenarios the doc describes. If the doc is thin for your platform, still **do not invent** a full generic ARIA layer—**follow the published doc** and, if the gap is blocking, call out that the behavior is not specified in CDS for that component. @@ -100,28 +100,28 @@ If the doc is thin for your platform, still **do not invent** a full generic ARI 1. If multiple CDS components could work, prefer the one whose **documentation** describes the right **focus management, keyboard, role, and announcements** for the interaction (e.g. a documented `Modal` or `Select` over a hand-built stack). 2. Prefer **smallest component whose doc fully covers the interaction** over a lower primitive plus custom behavior. -3. Defer to **`cds-code`** for overall “which component for layout/visuals”; use this step when **assistive technology behavior** is the differentiator. +3. Defer to **`cds-code`** for overall "which component for layout/visuals"; use this step when **assistive technology behavior** is the differentiator. ### Step 4: Apply documented accessibility APIs 1. **React Native:** set `accessibilityLabel`, `accessibilityHint`, `accessibilityState`, `accessibilityRole`, and any other props **the CDS component doc names** for the use case. Do not copy labels from old code without re-checking the current prop table. -2. **Web:** set `aria-*`, `as`, `role`, `htmlFor` / `id` / field wiring **only** as the CDS **web** component API and examples show. Prefer the component’s **first-class props** (e.g. a dedicated `label` or slot) over ad hoc ARIA on the wrong element. +2. **Web:** set `aria-*`, `as`, `role`, `htmlFor` / `id` / field wiring **only** as the CDS **web** component API and examples show. Prefer the component's **first-class props** (e.g. a dedicated `label` or slot) over ad hoc ARIA on the wrong element. 3. For **form validation and errors**, use the **CDS form patterns** the doc links—association and live regions must match the documented approach. -4. For **decorative vs informative** icons and images, follow CDS `Icon` / `Image` (or media) guidance in the **official** **CDS** doc (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)). +4. For **decorative vs informative** icons and images, follow CDS `Icon` / `Image` (or media) guidance in the **official** **CDS** doc (per **cds-docs**). 5. For **CDS `Text`** and **typography**, set **`as` (web)** / **`accessibilityRole` (React Native)** per **Part 2, Text (typography) and heading semantics** and the **Text** **official** doc (per **cds-docs**); skip if your change has no `Text` (or equivalent) in scope. ### Step 5: Focus management (focus-managed components only) -**When to run this step:** only if the Step 1 component list includes at least one **focus-managed** CDS component **per the published official doc** (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs))—typically **overlays and floating UI** (examples: **Modal**, **Tray**, **Tooltip**; also **drawer**, **popover**, or others **only if** the doc describes **focus** movement, **trap**, **initial/restore** focus, or **keyboard** dismiss). If the change is **only** static layout, inline fields, or components whose docs **do not** define focus management, **skip** this step and go to **Step 6: Verify**. +**When to run this step:** only if the Step 1 component list includes at least one **focus-managed** CDS component **per the published official doc** (per **cds-docs**)—typically **overlays and floating UI** (examples: **Modal**, **Tray**, **Tooltip**; also **drawer**, **popover**, or others **only if** the doc describes **focus** movement, **trap**, **initial/restore** focus, or **keyboard** dismiss). If the change is **only** static layout, inline fields, or components whose docs **do not** define focus management, **skip** this step and go to **Step 6: Verify**. -1. For **each** in-scope component, read the **official** **CDS** **.txt** (MCP: **`get-cds-doc`**; else **`curl`**, per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)) for **focus**, **keyboard**, **accessibility**, and any **ref/method** patterns. Use [cds.cbhq.net](https://cds.cbhq.net/) for worked examples that match your CDS version (e.g. web [Modal (overlay) – focus](https://cds.cbhq.net/components/overlay/Modal/)). +1. For **each** in-scope component, read the **official** **CDS** **.txt** (MCP: **`get-cds-doc`**; else **`curl`**, per **cds-docs**) for **focus**, **keyboard**, **accessibility**, and any **ref/method** patterns. Use the CDS documentation site for worked examples that match your CDS version (e.g. the Modal overlay focus section). 2. Implement **only** what the doc specifies: where focus **lands on open**, how **Tab** (or platform equivalent) **cycles within** the surface, how focus **restores on close**, and **dismiss** behavior (e.g. Esc) if documented. 3. **Do not** assume **Tooltip** behaves like **Modal**—hover vs click, `aria` behavior, and whether focus **moves** at all are **per component doc**. Do not add a home-grown `tabIndex`/listener stack when **CDS** already documents the path. ### Step 6: Verify 1. **Doc match:** your usage matches the **examples** and prop constraints in the doc you read (including platform-specific snippets). -2. If the doc or your team’s process expects a **device check** (e.g. VoiceOver on a build), note that; do not claim “accessible” from code shape alone if the task requires that verification. +2. If the doc or your team's process expects a **device check** (e.g. VoiceOver on a build), note that; do not claim "accessible" from code shape alone if the task requires that verification. 3. When the **`cds-code`** flow applies, keep its **visual** verification pass; this skill does not replace that—it adds **CDS a11y API** correctness. 4. **If you ran Step 5:** for each **focus-managed** component, confirm **open → focus** as documented, **Tab/keyboard cycle** as documented, **close → focus restore** as documented, and **dismiss** keys if the doc requires them. **If you skipped Step 5,** omit this bullet. @@ -134,22 +134,22 @@ If the doc is thin for your platform, still **do not invent** a full generic ARI ## Part 2: Consuming CDS for accessibility -These patterns are **not** a substitute for reading each component’s doc. They tell you **what to look for** in the **.txt** you got via **`get-cds-doc`**, **`curl`**, or any method defined in [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs) for the same route. +These patterns are **not** a substitute for reading each component's doc. They tell you **what to look for** in the **.txt** you got via **`get-cds-doc`**, **`curl`**, or any method defined in **cds-docs** for the same route. ### Doc discipline - **Prop names and values** must match the **current** published doc for your **major CDS version** in the repo. Do not paste snippets from old internal posts or from **web** into **React Native** without checking the right route. -- If something is **not in CDS** docs, this skill does not authorize inventing a full custom widget spec—escalate or use non-CDS guidance **outside** this skill’s scope. +- If something is **not in CDS** docs, this skill does not authorize inventing a full custom widget spec—escalate or use non-CDS guidance **outside** this skill's scope. ### Text (typography) and heading semantics -**You (the consumer)** are responsible for pairing **visual `font` styles** on CDS **`Text`** with **correct assistive names and roles** so structure matches the real page or screen. **Source of truth:** the **Text** **web** and **mobile** **official** docs (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs), **`get-cds-doc`** or **`curl`**) and the [Text (typography)](https://cds.cbhq.net/components/typography/Text/) page—not generic HTML heading blogs. +**You (the consumer)** are responsible for pairing **visual `font` styles** on CDS **`Text`** with **correct assistive names and roles** so structure matches the real page or screen. **Source of truth:** the **Text** **web** and **mobile** **official** docs (per **cds-docs**, **`get-cds-doc`** or **`curl`**) and the Text (typography) component doc—not generic HTML heading blogs. **Web (React):** - When **`Text`** is used for **headings** (commonly **`font`** values such as **display** or **title** when they represent section or page titles), set **`as`** to the **appropriate** heading element (`h1`–`h6`) so the **document outline** and screen readers match the **authoring** intent. Follow the **Text** **official** doc and **examples** for which **`font`** values pair with which **`as`**. -- For **`font`** values meant as **non-heading** copy—typically **body**, **headline** (emphasis, not a document heading), **label**, **caption**—**do not** set **`as`** to a **heading** (or other semantic) role when that would **misrepresent** structure (e.g. body text announced as a heading). If the **Text** doc is updated, the **official** **CDS** doc (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)) wins over this list. -- **Do not** add arbitrary rules from this skill such as “exactly one `h1` per page” or “every screen must include an `h1`” unless **CDS** documentation **explicitly** requires it for a pattern. Prefer **logical heading order** and product/IA; do **not** treat **headline** `font` as a **heading** role without checking the **Text** doc. +- For **`font`** values meant as **non-heading** copy—typically **body**, **headline** (emphasis, not a document heading), **label**, **caption**—**do not** set **`as`** to a **heading** (or other semantic) role when that would **misrepresent** structure (e.g. body text announced as a heading). If the **Text** doc is updated, the **official** **CDS** doc (per **cds-docs**) wins over this list. +- **Do not** add arbitrary rules from this skill such as "exactly one `h1` per page" or "every screen must include an `h1`" unless **CDS** documentation **explicitly** requires it for a pattern. Prefer **logical heading order** and product/IA; do **not** treat **headline** `font` as a **heading** role without checking the **Text** doc. **React Native:** @@ -159,25 +159,25 @@ These patterns are **not** a substitute for reading each component’s doc. They ### React Native (CDS mobile) -- Open each component’s **mobile** **official** **CDS** doc. Scan for: `accessibilityLabel`, `accessibilityHint`, `accessibilityState`, `accessibilityRole`, `accessible`, and any **CDS-prefixed** or forwarded props the doc lists. +- Open each component's **mobile** **official** **CDS** doc. Scan for: `accessibilityLabel`, `accessibilityHint`, `accessibilityState`, `accessibilityRole`, `accessible`, and any **CDS-prefixed** or forwarded props the doc lists. - Set **labels** for controls whose visible text is missing, ambiguous, or icon-only when the **doc** says to supply a name or when the **example** does. -- For **state** (selected, disabled, busy), use the patterns the **doc** shows—often `accessibilityState` in combination with the component’s own `disabled` / `value` props. +- For **state** (selected, disabled, busy), use the patterns the **doc** shows—often `accessibilityState` in combination with the component's own `disabled` / `value` props. - For **headings, lists, and navigational structure**, use CDS components whose **docs** define the right **role** and structure for RN VoiceOver (e.g. list cells vs flat `View` list). For **`Text`**, **heading** vs **body** treatment is covered in **Text (typography) and heading semantics** above. -- For **Modals, trays, tooltips**, and other **overlays** when the **mobile** doc describes **focus** or dismiss behavior, follow the **official** **CDS** **mobile** doc (per [cds-docs](https://skills.cbhq.net/skill/frontend/cds-public/cds-docs)) and **Part 1, Step 5** when that step applies—do not copy web-only focus patterns. +- For **Modals, trays, tooltips**, and other **overlays** when the **mobile** doc describes **focus** or dismiss behavior, follow the **official** **CDS** **mobile** doc (per **cds-docs**) and **Part 1, Step 5** when that step applies—do not copy web-only focus patterns. ### Web (CDS web) - Read the **web** **official** **CDS** doc for the component. Prefer **documentation** of: - **`as` and `role`** on `Box` and similar when the page needs **landmark or widget** semantics the doc allows. - - **`Text` / typography and headings** (**`as`** for real headings, not body/label/caption as headings): see **Text (typography) and heading semantics** above and [Text (typography)](https://cds.cbhq.net/components/typography/Text/). + - **`Text` / typography and headings** (**`as`** for real headings, not body/label/caption as headings): see **Text (typography) and heading semantics** above and the Text (typography) component doc. - **Labeling:** native `