Cds Code

CDS Code Writing Skill

Contents

1. Part 1: Initialization | Follow these steps once per session, before you write any code 2. Part 2: Workflow | Follow these steps for all frontend coding tasks

Part 1: Initialization

Perform the following operations only once per session, after the skill is activated.

Prepare CDS documentation

For any CDS documentation needs, you will need to use either of the following tools. If neither are available you may let the user know but still continue on with the task as documentation is helpful but not required.

• Activate the cds-docs skill OR...
• If the cds-docs skill is not configured, try calling the CDS MCP server list-cds-routes tool.

Environment Detection

You must determine if you are operating in a React or React Native project before you write any code.

1. Discover installed CDS packages and runtime

Run the bash discovery script: scripts/discover-cds-packages.sh

This will gve you:

• The CDS Runtime (web or mobile) - use this value as the platform argument for the CDS MCP server
• Every installed CDS package: its name, version, and valid export subpaths - these import paths are the ONLY ALLOWED PATHS for importing from CDS packages.

If you are unable to run the bash script, you can likely infer the platform by inspecting the project's source code.

2. Read the platform-specific styling and themeing documentation:

• getting-started/styling
• getting-started/theming

Part 2: Workflow

For all frontend coding tasks, you must follow these steps.

YOU MUST perform steps 1 and 2 before writing any code!

Step 1: Identify the appropriate components

Use guidelines/components.md to help identify the appropriate CDS components for the task. The guidelines file will cover most use cases, but you may optionally browse the CDS docs for the full list of supported CDS components.

If you decide your task will require icons (Icon or IconButton) or illustrations (SpotSquare, Pictogram, HeroSquare, etc.) please read the corresponding guidelines files for more details.

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.

If no CDS component fits your use case, you may fall back to the following options in this order of priority:

1. use a custom React component from the project's codebase 2. build your own custom React component 3. use the native platform's JSX elements for bespoke UI

IMPORTANT: Always inform the user which CDS components you are planning to use before moving on to Step 2.

Step 2: Optionally read component docs

For any CDS component you plan to use, retrieve and read their documentation (see Part 1 for more details on docs setup).

Step 3: Execute the task (writing frontend code)

Now create or update the UI with proper CDS components and usage.

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.

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.

You should check a component's props table in their CDS docs page to verify what props are available.

Example misuse of custom styles and their style props alternatives:

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.

Step 4: Validate changes

Your task will be complete if:

1. You performed initialization steps in Part 1 2. You examined the user's request and identified specific CDS components to use 3. Your changes DO NOT include any raw rgb/hex/etc color values 4. Your changes DO NOT use any raw pixel values for spacing, border radius, etc. 5. You changes use style props (e.g. font, color, textAlign, textTransform, padding, gap) instead of customization via style or with CSS. 6. All import paths are valid CDS package exports (see section below) 7. Any project linting/typechecking tasks are passing

Validating import paths

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).

Before writing or returning any CDS import, verify it against the export list from setup:

1. Find the CDS package for the target platform in the discovery script output. 2. Confirm the subpath you want to import is listed as a valid export. 3. If the subpath is not listed, it does not exist -- pick the closest valid export instead.

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.

Common mistakes to avoid:

• Inventing deep subpaths like <pkg>/layout/Box or <pkg>/buttons/Button when the actual export is <pkg>/layout or <pkg>/buttons.
• Guessing a package scope when the project uses a different one.
• Assuming that the CDS docs examples use the same package name as the target project -- they may differ.

CDS component selection guide

For full prop and type details, refer to the CDS component docs and TypeScript definitions; this guide is for _choosing_ components and patterns.

When the user describes a UI need, reach for these first:

Use the detailed sections below only when you need clarification; they intentionally avoid full prop API dumps and focus on when/why to pick a component plus key gotchas.

---

Categories

1. Layout 2. Typography 3. Buttons & Actions 4. Form Inputs 5. Overlays 6. Lists, Tables & Cards 7. Feedback & Status 8. Navigation 9. Media & Decoration 10. Visualization

---

1. Layout

Box

• What it is: Polymorphic layout primitive for flex/grid and simple block layouts.
• Use when: You need one‑off layout or styling that doesn’t fit a more specific component.
• Avoid marginX="auto" (not supported) — center with justifyContent="center" on the parent or alignSelf="center" on the child.

VStack / HStack

• What they are: Vertical and horizontal flex stacks — thin wrappers around Box with a fixed flex direction.
• Use when: You’re just stacking items with consistent spacing.
• Prefer these over Box when the intent is purely vertical/horizontal stacking.
• They accept all the same layout props as `Box` (padding, gap, background, borderRadius, etc.) — so never wrap <Box paddingX={2}><VStack> when you can just write <VStack paddingX={2}>.

Divider

• Horizontal or vertical rule to separate content.

Spacer

• Empty box to push siblings apart inside flex layouts.
• Prefer using gap on the parent; use Spacer only when you need explicit flexible space.

Responsive props

• Layout props accept responsive objects directly, e.g.:
• <VStack gap={{ phone: 1, tablet: 2, desktop: 3 }} />

---

2. Typography

• Use the generic `Text` component with a font prop for all text rendering — do not use the derivative shorthand components (TextTitle1, TextTitle2, TextTitle3, TextTitle4, TextHeadline, TextBody, TextLabel1, TextLabel2, etc.). Those are v7 patterns.
• The font prop accepts CDS type-scale tokens: "title1" – "title4", "headline", "body", "label1", "label2", "caption", etc.
• For muted/secondary text, use color="fgMuted" (not "foregroundMuted").
• Text is polymorphic via as and supports common text props (color, textAlign, textTransform, etc.).

Example:

<Text font="title3">Display Name</Text>
<Text font="body" color="fgMuted">user@example.com</Text>

---

3. Buttons & Actions

Button

• Primary click target for actions.
• Use for: Submits, primary/secondary/negative actions, full‑width CTAs (block).
• Key details:
• Uses onClick (not onPress).
• compact is the size control; there is no generic size prop.

IconButton

• Icon‑only action.
• Use for: Small, compact icon actions (close, edit, settings, etc.).
• Key details:
• Requires an accessibilityLabel describing the action.

ButtonGroup

• Wrap multiple Buttons for consistent spacing/alignment within a region (e.g., modal footers, form actions).

---

4. Form Inputs

Focus on which input to pick, not the full event/value API.

TextInput

• Single‑line text field.
• Use for: Freeform text, email, password, numeric, phone, URL, etc.
• For error states, rely on variants + helper text rather than a dedicated errorText prop.

Select

import { Select } from "@coinbase/cds-web/alpha/select";

• Dropdown for single or multi selection from a finite option set.
• Use for:
• Mutually exclusive options when there are many values (>5).
• Multi‑select of structured options.
• Uses an array of { value, label, disabled? } options rather than JSX children.

Combobox

import { Combobox } from "@coinbase/cds-web/alpha/combobox";

• Autocomplete / typeahead control.
• Use when: The user types to filter a relatively long list of options.

SelectChip

import { SelectChip } from "@coinbase/cds-web/alpha/select-chip";

• Filter chip that opens a dropdown of options.
• Use when: You want a compact, chip‑style filter control (e.g., filtering lists/tables).

Switch

• On/off toggle.
• Use for: Single boolean settings.

Checkbox + ControlGroup

• Use Checkbox for independent toggles or lists of multi‑select items.
• Group multiple checkboxes inside ControlGroup role="group" when they belong together.

Radio + ControlGroup

• Use for: Mutually exclusive options where each option is always visible.
• Wrap radios in ControlGroup role="radiogroup".

SegmentedTabs

• Tab‑style picker for 2–5 mutually exclusive options (a more compact alternative to radios).

DateInput / DatePicker

• Date inputs where the value is an ISO string and selection semantics matter.
• Use when users must pick specific calendar dates, not just arbitrary strings.

Slider

• Numeric range selector or single value on a continuum.
• Use when dragging a handle is more intuitive than typing numbers.

SearchInput

• Preset TextInput variant with search icon and clear button.
• Use for primary search bars and filter/search fields.

Form composition helpers

• Field: Wraps any input with label + helper/error text.
• FieldLabel, FieldHelperText, FieldErrorText: Low‑level building blocks.
• Use these to keep labels and error messaging consistent across custom compositions.

---

5. Overlays

Modal

• Centered overlay dialog.
• Use for: Blocking flows requiring focused attention and explicit dismissal.
• Key details:
• No title/description props directly on Modal; compose with ModalHeader, ModalBody, and ModalFooter.

ModalHeader, ModalBody, ModalFooter

• ModalHeader: Provides the title and optional description.
• ModalBody: Scrollable content region.
• ModalFooter: Primary/secondary actions (expects actual Button elements, not strings or bare onClick handlers).

Tray

• Bottom‑sheet style overlay (mobile‑first).
• Use for: Flows that feel lighter than full modals, especially on mobile.

Popover

• Anchored floating panel near a trigger element.
• Use for: Contextual menus or small pieces of interactive content anchored to a control.
• Key detail: Trigger/anchor is the children of Popover, not a separate trigger prop. Positioning lives in contentPosition.

Tooltip

• Small hover/focus hint attached to a single child element.
• Use for: Short, non‑essential explanations of controls and icons.

useToast (hook)

• Imperative toasts for transient success/error/info feedback.
• Use for: "Saved successfully", "Could not connect", etc.
• Do not render a <Toast /> directly; rely on useToast().show(...).

---

6. Lists, Tables & Cards

ListCell

• Row primitive for lists, settings, and menus.
• Use for: Settings lists, profile lists, navigation lists, etc.
• Use media for leading visuals and accessory / accessoryNode / end for trailing content; see CDS docs for the full API.

Table

• Tabular data presentation.
• Use for: Dense data, sortable columns, and paginated datasets.

Accordion / AccordionItem

• Expand/collapse regions for content that doesn’t need to be visible all at once.

ContentCard (+ ContentCardHeader, ContentCardBody, ContentCardFooter)

• Standard composable card.
• Use wherever you previously used generic Card components.

MediaCard

• Card with a prominent media area (e.g., image, illustration).
• Use for content that is visually led (promos, featured content).

MessagingCard

• In‑product messaging card.
• Use for: Upsells, nudges, announcements, and similar messaging blocks.
• Uses a type to differentiate visual style (e.g., 'upsell', 'nudge').

DataCard

import { DataCard } from "@coinbase/cds-web/alpha/data-card";

• Card for summarizing key data points (metrics, balances).
• Use for: Dashboard tiles and summary metrics; always prefer this implementation over legacy DataCard.

Fallback

• Skeleton / placeholder shape.
• Use for: Loading states where you know the final structure but not the data yet.

---

7. Feedback & Status

Tag

• Small status/label pill (there is no Badge in CDS).
• Use for: Status indicators, small inline labels and tags.

Banner

• Inline page‑level alert.
• Use for: Warnings, promotional messages, informational notes, and errors that sit inline with content.
• Takes a variant (warning/promotional/informational/error) and optional actions via Link components.

ProgressCircle

• Circular progress indicator from @coinbase/cds-web-visualization.
• Use for:
• indeterminate loading spinners.
• Determinate progress when you want circular visuals instead of bars.

ProgressBar

• Linear determinate progress from @coinbase/cds-web-visualization.
• Use for: Long‑running operations where linear progress is easy to interpret.

---

8. Navigation

Tabs

• Composable tab bar using a tabs data array and controlled activeTab.
• Use for: Section switching where each tab corresponds to a different view.

SegmentedTabs

• Higher‑level wrapper around Tabs for 2–5 mutually exclusive options.
• Use when: You want simple segmented controls.

TabbedChips

import { TabbedChips } from "@coinbase/cds-web/alpha/tabbed-chips/TabbedChips";

• Chip‑styled tabs.
• Use for: Horizontally scrolling chip‑like navigation with overflow handling.

Pagination

• Pagination control.
• Use for: Paged results in tables or content feeds.

Stepper

• Multi‑step progress indicator.
• Use for: Wizards, onboarding flows, and any multi‑step process, vertically or horizontally.

---

9. Media & Decoration

Avatar

• Avatar: Single user/entity image with initials fallback.
• Use for: Representing people, accounts, or entities.

Icon

• Single glyph icon.
• Use for: Supplementary visual cues; pair with labels for clarity and accessibility.

Image / RemoteImage

• Display bitmap images with control over object fit, size, and border radius.

SpotSquare

• Decorative square illustration, often used inside cards or list rows.

Pictogram

• Decorative pictogram for more illustrative moments.

Logo

• Coinbase wordmark or symbol.
• Use for: Brand marks; pick variant and color that match the context.

---

10. Visualization

From @coinbase/cds-web-visualization.

Charts

• LineChart, BarChart, AreaChart, PieChart.
• Use for: Time series, comparisons, distributions, and proportions, respectively.
• Configure via data, axes, and series definitions.

Legend

• Standalone legend component to accompany charts.

Customizing styles

Prefer using CDS Design Tokens as values over hardcoded values. Examples:

• On web, prefer marginTop: 'var(--space-0_5)' over marginTop: '4px'.
• On web, prefer borderRadius: 'var(--borderRadius-200)' over borderRadius: '8px'.
• On mobile, prefer marginTop: theme.space[0.5] over marginTop: 4.
• On mobile, prefer borderRadius: theme.borderRadius[200] over borderRadius: 8.
• Prefer <Box background="bgAlternate" padding={2} /> over a custom wrapper with hardcoded CSS.

style on Select

import { memo, useState } from 'react';
import { Select } from '@coinbase/cds-web/alpha/select'; // or '@coinbase/cds-mobile/alpha/select'
import { VStack } from '@coinbase/cds-web/layout'; // or '@coinbase/cds-mobile/layout'

const selectOptions = [
  { value: 'option1', label: 'Option 1', description: 'Description' },
  { value: 'option2', label: 'Option 2', description: 'Description' },
  { value: 'option3', label: 'Option 3', description: 'Description' },
];

export const SelectExample = memo(() => {
  const [selectValue, setSelectValue] = useState<string | null>(null);

  return (
    <VStack>
      <Select
        compact
        label="Label"
        labelVariant="inside"
        onChange={setSelectValue}
        options={selectOptions}
        placeholder="Select an option"
        style={{ flexGrow: 1 }}
        value={selectValue}
      />
      <Select
        label="Label"
        onChange={setSelectValue}
        options={selectOptions}
        placeholder="Select an option"
        style={{ flexGrow: 1 }}
        value={selectValue}
      />
    </VStack>
  );
});

styles on Select

import { useState } from 'react';
import { Select } from '@coinbase/cds-web/alpha/select'; // or '@coinbase/cds-mobile/alpha/select'

function CustomStylesExample() {
  const [value, setValue] = useState('1');
  const options = [
    { value: null, label: 'Remove selection' },
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4' },
  ];

  return (
    <Select
      label="Single select - styles"
      onChange={setValue}
      options={options}
      styles={{
        control: {
          padding: '20px',
          backgroundColor: 'lightgray',
        },
        controlBlendStyles: {
          background: 'coral',
          hoveredBackground: 'crimson',
          pressedBackground: 'red',
        },
        optionBlendStyles: {
          background: 'lightblue',
          hoveredBackground: 'blue',
        },
        dropdown: {
          padding: '20px',
          backgroundColor: 'pink',
        },
      }}
      value={value}
    />
  );
}

styles on ContentCell

import { ContentCell } from '@coinbase/cds-web/cells'; // or '@coinbase/cds-mobile/cells'
import { Avatar } from '@coinbase/cds-web/media'; // or '@coinbase/cds-mobile/media'

<ContentCell
  spacingVariant="condensed"
  title="Profile Information"
  subtitle="Active Status"
  media={<Avatar alt="Sneezy" name="Sneezy" size="m" colorScheme="blue" />}
  accessory="disclosure"
  description="This example demonstrates the use of media (avatar) and an accessory indicator."
  styles={{
    media: {
      paddingTop: 'var(--space-0_5)',
    },
  }}
/>;

Web-only classNames plus styles

classNames is a web pattern. On mobile, use styles only.

import { css } from '@linaria/core';
import { DotCount } from '@coinbase/cds-web/dots';
import { VStack } from '@coinbase/cds-web/layout';
import { useTheme } from '@coinbase/cds-web';

const dotCountContainerCss = css`
  border-radius: 4px;
`;

function DotCountStyle() {
  const theme = useTheme();

  return (
    <VStack alignItems="flex-start" gap={1}>
      <DotCount
        classNames={{
          container: dotCountContainerCss,
        }}
        count={30}
        styles={{
          container: {
            backgroundColor: theme.color.bgPositive,
            borderColor: theme.color.fg,
          },
        }}
      />
    </VStack>
  );
}

styles on layout containers

import { Carousel } from '@coinbase/cds-web/carousel'; // or '@coinbase/cds-mobile/carousel'

<Carousel styles={{ carousel: { gap: 16 } }}>{/* carousel items */}</Carousel>;

Notes

• Use the same component patterns across web and mobile when you can, and swap the import paths.
• Web components often support className and classNames; mobile customization is usually style or styles.
• styles is usually slot-based, so use the documented keys like control, dropdown, media, or container.
• If layout props can solve it, prefer those over custom styling. Save style and styles for exceptions.

Icons

Use this guide when the task needs CDS icons.

Find icons

Use the discovery script (scripts/discover-cds-icons.mjs) to list all availabe icons in the installed version of CDS.

Sample usage:

• node skills/cds-code/scripts/discover-cds-icons.mjs <query>
• node skills/cds-code/scripts/discover-cds-icons.mjs <query> --limit 10
• node skills/cds-code/scripts/discover-cds-icons.mjs <query> --all
• node skills/cds-code/scripts/discover-cds-icons.mjs <query> --project-root /absolute/path/to/app

If you are unable to run the script, retrieve the Icon page from the CDS docs.

Size guidance

• Supported sizes: xs, s, m, l
• Icon default size is m
• IconButton defaults to s when compact and m when not compact
• Navigation/sidebar icon usage is usually m
• Dense inline usage (for example caret affordances) is commonly s

Active state guidance

• Use active only for selected/toggled states (for example selected bottom nav item, selected sidebar row, toggled IconButton)
• Selected icons are often paired with selected color treatment in the surrounding component state

Illustrations

Use this guide when the task needs CDS illustrations.

Find illustrations

Use the discovery script (scripts/discover-cds-illustrations.mjs) to list all availabe illustrations in the installed version of CDS.

Sample usage:

• node skills/cds-code/scripts/discover-cds-illustrations.mjs <query>
• node skills/cds-code/scripts/discover-cds-illustrations.mjs <query> --limit 12
• node skills/cds-code/scripts/discover-cds-illustrations.mjs <query> --all
• node skills/cds-code/scripts/discover-cds-illustrations.mjs <query> --variant Pictogram
• node skills/cds-code/scripts/discover-cds-illustrations.mjs <query> --project-root /absolute/path/to/app

If you are unable to run the script, retrieve the appropriate pages from the CDS docs.

Variants

Components: Pictogram, SpotIcon, SpotSquare, SpotRectangle, HeroSquare

Dimension guidance

• Pictogram: 48x48 (default), 64x64
• SpotIcon: 32x32 (default), 24x24
• SpotSquare: 96x96 (default)
• SpotRectangle: 240x120 (default)
• HeroSquare: 240x240 (default), 200x200

Pick the closest supported dimension for the layout instead of inventing new values.

cds-code

Helps your agent write idiomatic Coinbase Design System (CDS) code for React or React Native projects.

We recommend also installing the cds-docs Skill or the CDS MCP server for even better performance!

npx skills add https://github.com/coinbase/cds --skill cds-docs

Running evaluations

Use the skill-creator skill to run the evals.

First install the skill-creator skill if it is not already:

npx skills add https://github.com/anthropics/skills --skill skill-creator

Run evals by prompting your agent:

Use the skill-creator skill to run the evals for the cds-code skill