You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: skills/cds-code/README.md
+26-1Lines changed: 26 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,38 @@
1
1
# cds-code
2
2
3
-
Helps your agent write idiomatic Coinbase Design System (CDS) code for React or React Native projects.
3
+
Helps your agent write idiomatic Coinbase Design System (CDS) code for React or React Native projects. Also supports CDS code review — ask your agent to audit a feature or set of files for CDS adherence.
4
4
5
5
We recommend also installing the `cds-docs` Skill or the CDS MCP server for even better performance!
The biggest gains come from domain-specific knowledge the base model lacks: CDS mobile primitives, deprecated API awareness, illustration component selection, and structured audit-format output.
Produces high quality Coinbase Design System (CDS) code for React and React Native projects.
5
-
Always use this skill every time you are asked to create or update UI or write React or React Native code.
4
+
Provides a structured workflow for writing high quality Coinbase Design System (CDS) code.
5
+
Use this skill every time you are asked to create or update a user interface using React or React Native.
6
+
Additinoally, this skill may be used to conduct a code review on existing code for CDS adherence.
7
+
Trigger examples: "build this screen", "update this component", "perform a CDS audit on our changes",
8
+
"check our codebase for CDS adherence", "does this feature use CDS well?"
6
9
license: Apache-2.0
7
10
metadata:
8
-
version: '2.0.0'
11
+
version: '2.1.0'
9
12
---
10
13
11
-
# CDS Code Writing Skill
14
+
# CDS Code Skill
12
15
13
-
## Contents
16
+
## On every request
14
17
15
-
1. Part 1: Initialization | Follow these steps once per session, before you write any code
16
-
2. Part 2: Workflow | Follow these steps for all frontend coding tasks
18
+
Before responding, determine what the user needs:
17
19
18
-
## Part 1: Initialization
20
+
**Coding** — the user wants to create or update UI → follow the Coding Workflow.
19
21
20
-
Perform the following operations only once per session, after the skill is activated.
22
+
**Review** — the user explicitly asks to audit, review, or check existing code for CDS adherence → read `guidelines/code-review.md` and follow it instead.
21
23
22
-
### Prepare CDS documentation
24
+
**Default to coding.** Only treat a request as a review if the user's intent is explicit. Writing code is the primary use case for this skill.
23
25
24
-
For any CDS documentation needs, you will need to use either of the following tools.
25
-
If neither are available you may let the user know but still continue on with the task as documentation is helpful but not required.
26
+
## Initialization
26
27
27
-
- Activate the `cds-docs` skill OR...
28
-
- If the `cds-docs` skill is not configured, try calling the CDS MCP server `list-cds-routes` tool.
28
+
Run this once per session, before doing anything else.
29
29
30
-
### Environment Detection
30
+
Run the discovery script: `scripts/discover-cds-packages.sh`
31
31
32
-
You must determine if you are operating in a React or React Native project before you write any code.
32
+
Its output tells you:
33
33
34
-
1.**Discover installed CDS packages and runtime**
34
+
- The `CDS Runtime` (`web` or `mobile`) — use this value as the `platform` argument for the CDS MCP server if it is needed.
35
+
- Every installed CDS package: its name, version, and valid export subpaths — these import paths are the ONLY ALLOWED PATHS when importing from CDS packages
35
36
36
-
Run the `bash` discovery script: `scripts/discover-cds-packages.sh`
37
+
If the script cannot be run, much of the information it provides can be determined via manual inspection:
37
38
38
-
This will gve you:
39
+
- Infer the platform by inspecting existing CDS imports in the project's source code
40
+
- Find valid import paths by reading the `exports` field of the `package.json` of installed CDS packages in `node_modules`
39
41
40
-
- The `CDS Runtime` (`web` or `mobile`) - use this value as the `platform` argument for the CDS MCP server
41
-
- Every installed CDS package: its name, version, and valid export subpaths - these import paths are the ONLY ALLOWED PATHS for importing from CDS packages.
42
+
## Coding Workflow
42
43
43
-
If you are unable to run the bash script, you can likely infer the `platform` by inspecting the project's source code.
44
+
For all frontend coding tasks, follow these steps in order.
44
45
45
-
2. Read the platform-specific styling and themeing documentation:
46
+
**YOU MUST** perform steps 1 and 2 before writing any code!
46
47
47
-
-`getting-started/styling`
48
-
-`getting-started/theming`
48
+
### Step 1: Prepare CDS documentation
49
+
50
+
For any CDS documentation needs, use either of the following tools.
51
+
If neither are available, let the user know but continue — documentation is helpful but not required.
49
52
50
-
## Part 2: Workflow
53
+
- Activate the `cds-docs` skill OR...
54
+
- If the `cds-docs` skill is not configured, try calling the CDS MCP server `list-cds-routes` tool.
51
55
52
-
For all frontend coding tasks, you must follow these steps.
56
+
Then read the platform-specific docs (using the runtime detected in Initialization):
53
57
54
-
**YOU MUST** perform steps 1 and 2 before writing any code!
58
+
-`getting-started/styling`
59
+
-`getting-started/theming`
55
60
56
-
### Step 1: Identify the appropriate components
61
+
### Step 2: Identify the appropriate components
57
62
58
63
Use `guidelines/components.md` to help identify the appropriate CDS components for the task.
59
64
The guidelines file will cover most use cases, but you may optionally browse the CDS docs for the full list of supported CDS components.
@@ -64,31 +69,48 @@ If you decide your task will require icons (`Icon` or `IconButton`) or illustrat
If the task involves icons, also follow `guidelines/icons.md` and use `scripts/discover-cds-icons.mjs` to search icon names. If the task involves illustrations, also follow `guidelines/illustrations.md` and use `scripts/discover-cds-illustrations.mjs` to search illustration names.
68
-
69
72
If no CDS component fits your use case, you may fall back to the following options in this order of priority:
70
73
71
-
1. use a custom React component from the project's codebase
72
-
2. build your own custom React component
73
-
3. use the native platform's JSX elements for bespoke UI
74
+
1. search for a relevant and reusable React component from the project's codebase to use
75
+
2. build your own custom React component using CDS primitives as building blocks
76
+
3. use the native platform's JSX elements (div, View, etc.) for bespoke UI as a last resort
77
+
78
+
**IMPORTANT:** Always inform the user which CDS components you are planning to use before moving on to Step 3.
74
79
75
-
**IMPORTANT:** Always inform the user which CDS components you are planning to use before moving on to `Step 2`.
80
+
### Step 3: Optionally read component docs
76
81
77
-
### Step 2: Optionally read component docs
82
+
For any CDS component you plan to use, retrieve and read their documentation (see Step 1 in this workflow for more details on docs setup).
78
83
79
-
For any CDS component you plan to use, retrieve and read their documentation (see `Part 1`for more details on docs setup).
84
+
If documentation is not retrievable for any reason, the published type definitions for the component may be used to determine the full props API a component affords. This is no substitute for reading the documentation, but it can be a useful fallback when documentation is not available.
80
85
81
-
### Step 3: Execute the task (writing frontend code)
86
+
### Step 4: Execute the task (writing code)
82
87
83
88
Now create or update the UI with proper CDS components and usage.
84
89
85
-
Most CDS component implement an API that allows you to apply the CDS design tokens, we call these 'style props'. Prefer setting these style props for styling components over setting custom style via inline styles or CSS.
90
+
#### Package scope
91
+
92
+
The package name may vary between projects. Different repos may install CDS under different scopes.
93
+
Always match the full CDS package name(s) as determined in the initialization step. If the project already has CDS imports in existing code, match whatever scope those files use.
94
+
95
+
#### Using the Design System
96
+
97
+
In most cases, you should avoid using inline style objects or CSS classNames (web only).
98
+
Through these methods it is very easy to make common mistakes like using hardcoded property values instead of the CDS design tokens.
99
+
Doing so would break the component's connection to the CDS theme.
100
+
101
+
If you must use a style object or a CSS className, you can still access the CDS theme either through the `useTheme` hook or by CSS variables (web only).
102
+
103
+
Most CDS components implement an API that conveniently allows you to apply CDS design tokens, internally we call these 'style props'.
104
+
105
+
In cds-web, style props essentially act as an API for applying atomic CSS classes, much like Tailwind's utility classes which are so prevelant in the web ecosystem.
106
+
107
+
You should prefer setting these style props for styling components over setting custom style via inline styles or CSS.
86
108
87
109
**Why this matters:** When you set `font`, `color`, `textAlign`, or other typography properties through `style` instead of props, the component loses its connection to the CDS theme. For example, setting `fontSize` and `fontWeight` via `style` without a `font` prop means the CDS font family never applies -- the text falls back to `inherit` and may render in the wrong typeface.
88
110
89
-
You should check a component's props table in their CDS docs page to verify what props are available.
111
+
You should check a component's documentation which includes a props table to verify the available API.
90
112
91
-
Example misuse of custom styles and their style props alternatives:
113
+
Examples of opportunities to use style props over inline styles:
If you need to further customize the style of a rendered CDS component or a specific style is not support via style props, you may reference: `guidelines/customizing-styles.md`.
105
-
106
-
### Step 4: Validate changes
126
+
### Step 5: Validate changes
107
127
108
128
Your task will be complete if:
109
129
110
-
1. You performed initialization steps in `Part 1`
111
-
2. You examined the user's request and identified specific CDS components to use
112
-
3. Your changes DO NOT include any raw rgb/hex/etc color values
113
-
4. Your changes DO NOT use any raw pixel values for spacing, border radius, etc.
114
-
5. You changes use style props (e.g. `font`, `color`, `textAlign`, `textTransform`, `padding`, `gap`) instead of customization via `style` or with CSS.
115
-
6. All import paths are valid CDS package exports (see section below)
116
-
7. Any project linting/typechecking tasks are passing
117
-
118
-
#### Validating import paths
119
-
120
-
**This is critical.** Do not guess or memorize CDS import paths. The discovery script output is the source of truth (see `Part 1` for details).
121
-
122
-
Before writing or returning any CDS import, verify it against the export list from setup:
123
-
124
-
1. Find the CDS package for the target platform in the discovery script output.
125
-
2. Confirm the subpath you want to import is listed as a valid export.
126
-
3. If the subpath is not listed, it does not exist -- pick the closest valid export instead.
127
-
128
-
**The package name may vary between projects.** Different repos may install CDS under different scopes. Always use the package name reported by the discovery script, not a hardcoded scope. If the project already has CDS imports in existing code, match whatever scope those files use.
129
-
130
-
Common mistakes to avoid:
131
-
132
-
- Inventing deep subpaths like `<pkg>/layout/Box` or `<pkg>/buttons/Button` when the actual export is `<pkg>/layout` or `<pkg>/buttons`.
133
-
- Guessing a package scope when the project uses a different one.
134
-
- Assuming that the CDS docs examples use the same package name as the target project -- they may differ.
130
+
1. You performed skill initialization and explicitly identified the specific CDS components you would use
131
+
2. Your changes DO NOT include any raw rgb/hex/etc color values
132
+
3. Your changes DO NOT use any raw pixel values for spacing properties (padding, margin, gap, border radius). Explicit layout dimensions like `width` or `height` set to specific designer-specified values are acceptable.
133
+
4. Your changes DO NOT import any depreacted CDS components or hooks.
134
+
5. Your changes use components' style props (e.g. `font`, `color`, `background`, `textTransform`, `paddingX`, `gap`) instead of customization via inline `style` objects or with CSS classNames.
135
+
6. All import paths are valid CDS package exports, determined in initialization
136
+
7. The project's linting/typechecking/formatting tasks are passing
0 commit comments