@coinbase/cds-mcp-server 8.17.2 → 8.17.4

package/mcp-docs/mobile/getting-started/installation.txt

@@ -0,0 +1,57 @@
+# installation
+
+This guide will help you get started with installing CDS in your React Native project. Follow the instructions below to set up CDS and start building with our cross-platform components.
+
+### Installation
+
+To install the CDS library for React Native applications, run the following command:
+
+```bash
+npm install @coinbase/cds-mobile
+```
+
+Alternatively, if you are using Yarn:
+
+```bash
+yarn add @coinbase/cds-mobile
+```
+
+:::tip
+For React Native projects, ensure you have set up your environment for React Native development. Refer to the [React Native Environment Setup Guide](https://reactnative.dev/docs/environment-setup) if needed.
+:::
+
+### Getting started
+#### 1. Render a ThemeProvider
+
+Render a ThemeProvider at the root of your application, and pass the `theme` and `activeColorScheme`.
+
+```tsx
+import { ThemeProvider } from '@coinbase/cds-mobile';
+import { defaultTheme } from '@coinbase/cds-mobile/themes/defaultTheme';
+import App from './App';
+
+const Index = () => (
+  <ThemeProvider theme={defaultTheme} activeColorScheme="light">
+    <App />
+  </ThemeProvider>
+);
+
+export default Index;
+```
+
+#### 2. Verify the installation
+
+Try importing and rendering a simple CDS component.
+
+```tsx
+import { Button } from '@coinbase/cds-mobile/buttons';
+
+const Test = () => <Button>Click Me</Button>;
+```
+
+### Next steps
+
+Learn how to customize CDS's appearance.
+
+[See the theming docs here &rarr;](/getting-started/theming)
+

package/mcp-docs/mobile/getting-started/introduction.txt

@@ -0,0 +1,102 @@
+---
+id: introduction
+title: Introduction
+hide_title: true
+---
+
+import { VStack } from '@coinbase/cds-web/layout';
+import { MDXSection } from '@site/src/components/page/MDXSection';
+import { MDXArticle } from '@site/src/components/page/MDXArticle';
+import { ContentHeader } from '@site/src/components/page/ContentHeader';
+import { GettingStartedBanner } from '@site/src/components/page/ComponentBanner/GettingStartedBanner';
+
+<VStack gap={5}>
+<ContentHeader
+  title="Introduction"
+  description="Coinbase Design System is a cross-platform component library for React and React Native. CDS has high adoption in every product at Coinbase, accelerating development and ensuring a consistent user experience across all platforms."
+  banner={<GettingStartedBanner />}
+/>
+
+<MDXSection>
+<MDXArticle>
+## Key features
+
+- **Cross-platform** - CDS provides components for both React DOM and React Native. We go to great lengths to ensure that the source code is as identical as possible across React and React Native without compromising on platform-specific features.
+
+- **Powerful theming** - The ThemeProvider can be used to define a custom theme for your application supporting light and dark mode.
+
+- **Rich styling capabilities** - Components are designed to integrate with third-party libraries like styled-components, and to be customizable via theming, props, StyleProps, classnames, and inline styles.
+
+- **Subcomponent composition** - Components are built using smaller subcomponents that can be fully customized or replaced via props.
+
+- **Accessibility** - Components are accessible out of the box, and can be customized to different accessibility standards.
+
+</MDXArticle>
+</MDXSection>
+
+<MDXSection>
+<MDXArticle>
+## Web-only features
+
+- **Atomic static CSS** - CSS is compiled to atomic static classnames at library build time.
+
+- **Responsive styles** - Components support responsive styles out of the box. Use the responsive syntax to adjust layouts and styles based on device breakpoints without writing custom media queries.
+
+- **CSS layers** - All CSS is added to the `cds` layer. This allows you to easily override CDS styles with your own styles.
+
+- **Polymorphic components** - Components can be rendered as different HTML elements or as other components.
+
+</MDXArticle>
+</MDXSection>
+
+<MDXSection>
+<MDXArticle>
+## Developer experience
+
+CDS is designed to make your development workflow as smooth as possible.
+
+- **TypeScript first** - Full type safety with excellent IDE autocomplete for props, theme values, and style props. Most mistakes are caught at compile time.
+
+- **Flexible styling** - Use the StyleProps API for rapid development with theme-aware values, or drop down to className and style props for full control. Mix and match approaches as needed.
+
+- **Component composition** - Build complex UIs by composing simple primitives. Most components expose subcomponents that can be customized or replaced entirely.
+
+- **Performance optimized** - All web components use atomic CSS with zero runtime overhead. CSS is generated at build time and styles are applied via static classnames.
+
+- **Extensive documentation** - Every component includes Storybook stories, interactive examples, detailed prop tables, and usage guidelines.
+
+```jsx
+import { ThemeProvider } from '@coinbase/cds-web';
+import { defaultTheme } from '@coinbase/cds-web/themes/defaultTheme';
+import { Box } from '@coinbase/cds-web/layout';
+import { Text } from '@coinbase/cds-web/typography';
+import { Button } from '@coinbase/cds-web/buttons';
+
+const App = () => (
+  <ThemeProvider theme={defaultTheme} activeColorScheme="light">
+    <Box padding={4} background="bgPrimary" borderRadius={200}>
+      <Text font="title1" color="fg">
+        Welcome to CDS
+      </Text>
+      <Button variant="positive" marginTop={2}>
+        Get started
+      </Button>
+    </Box>
+  </ThemeProvider>
+);
+```
+
+</MDXArticle>
+</MDXSection>
+
+<MDXSection>
+<MDXArticle>
+## Next steps
+
+Learn how to install and use CDS.
+
+[See the installation docs here →](/getting-started/installation)
+
+</MDXArticle>
+</MDXSection>
+</VStack>

package/mcp-docs/mobile/getting-started/playground.txt

@@ -0,0 +1,28 @@
+---
+id: playground
+title: Playground
+hide_title: true
+---
+
+import { VStack } from '@coinbase/cds-web/layout';
+import { MDXSection } from '@site/src/components/page/MDXSection';
+import { MDXArticle } from '@site/src/components/page/MDXArticle';
+import { ContentHeader } from '@site/src/components/page/ContentHeader';
+import { PlaygroundBanner } from '@site/src/components/page/ComponentBanner/PlaygroundBanner';
+import { ShareablePlayground } from '@site/src/components/page/ShareablePlayground';
+
+<VStack gap={5}>
+<ContentHeader
+  title="Playground"
+  description="Live code playground for testing and sharing CDS components and code examples. All CDS components and hooks and all React exports are available to use in the playground without importing them. You must call render() to render your code."
+  banner={<PlaygroundBanner />}
+/>
+
+<MDXSection>
+<MDXArticle>
+
+<ShareablePlayground />
+
+</MDXArticle>
+</MDXSection>
+</VStack>

package/mcp-docs/mobile/getting-started/styling.txt

@@ -0,0 +1,84 @@
+# styling
+
+CDS includes powerful and flexible APIs for styling components. Easily access values from the theme, or go rogue with full customization.
+
+### `StyleProps` API
+
+Most components support the StyleProps API. StyleProps automatically have access to the values in the theme, and some StyleProps are limited to only the theme values.
+
+[See the full list of StyleProps here →](/components/layout/Box/?platform=mobile&tab=props)
+
+```jsx
+// ✅ The `bgNegative` token will automatically update with the theme!
+<Box background="bgNegative" width={100} />
+
+// ❌ Error: Type '"#0000ff"' is not assignable to type 'Color | undefined'.
+<Box background="#0000ff" width={100} />
+```
+
+:::tip
+The docs page of every component has a props table listing all the available props!
+:::
+
+:::note
+The StyleProps API uses the ThemeProvider Context under the hood to enable dynamic theming.
+:::
+
+### `style` and `styles` props
+
+Most components support the native `style` prop for inline styles.
+
+```jsx
+<Box style={{ backgroundColor: '#0000ff' }} />
+```
+
+Some complex components support passing inline styles to subcomponents with the `styles` prop.
+
+```jsx
+<ProgressCircle
+  styles={{
+    circle: {
+      stroke: 'transparent',
+    },
+    progress: {
+      strokeLinecap: 'square',
+    },
+  }}
+  color="fgPositive"
+  progress={0.75}
+  size={100}
+/>
+```
+
+Styles are combined using React Native's style arrays, and are added in order of specificity.
+
+```jsx
+<PageHeader style={{ backgroundColor: 'red' }} styles={{ root: { backgroundColor: 'blue' } }} />
+```
+
+In the example above, `backgroundColor` will be blue.
+
+:::tip
+We will continue to add the `styles` prop to more components over time. Please feel free to request specific components that you think would benefit from this API.
+:::
+
+### Component specific props
+
+Many components have their own specific props that can affect styling.
+
+```jsx
+<Button compact variant="primary">
+  Click me
+</Button>
+```
+
+### Combining techniques
+
+Mix and match these styling techniques for complete customization!
+
+```jsx
+<Button variant="primary" borderColor="accentBoldPurple" style={{ fontFamily: 'Times' }}>
+  Click me
+</Button>
+```
+

package/mcp-docs/mobile/getting-started/theming.txt

@@ -0,0 +1,286 @@
+# theming
+
+The theme contains design tokens like colors, fonts, spacing, and more. The ThemeProvider provides access to these values via CSS Variables for web, and React Context for both web and React Native.
+
+import { defaultTheme } from '@coinbase/cds-mobile/themes/defaultTheme';
+import { JSONCodeBlock } from '@site/src/components/page/JSONCodeBlock';
+
+### ThemeProvider component
+
+The ThemeProvider provides the theme context to all child components.
+
+You must pass the `theme` prop to configure the theme, and the `activeColorScheme` prop to set light or dark mode.
+
+[See the ThemeProvider docs here →](/components/other/ThemeProvider)
+
+```tsx
+import { ThemeProvider } from '@coinbase/cds-mobile/system/ThemeProvider';
+import { defaultTheme } from '@coinbase/cds-mobile/themes/defaultTheme';
+
+const App = () => (
+  <ThemeProvider theme={defaultTheme} activeColorScheme="light">
+    {/* Your app components */}
+  </ThemeProvider>
+);
+```
+
+:::tip
+Changing the `activeColorScheme` automatically updates the values returned from the `useTheme` hook.
+:::
+
+#### `useTheme` hook
+
+The `useTheme` hook provides access to the current `theme` and `activeColorScheme`.
+
+The `color` and `spectrum` objects automatically change based on the `activeColorScheme`.
+
+[See the `useTheme` docs here &rarr;](/hooks/useTheme)
+
+```jsx
+const theme = useTheme();
+theme.activeColorScheme; // "light" or "dark"
+theme.spectrum; // Resolves to lightSpectrum or darkSpectrum, depends on activeColorScheme
+theme.color; // Resolves to lightColor or darkColor, depends on activeColorScheme
+theme.color.bgPrimary; // "rgb(0,82,255)" or "rgb(87,139,250)", depends on activeColorScheme
+theme.space[2]; // 16
+theme.borderRadius[200]; // 8
+theme.fontSize.display3; // 40
+```
+
+#### Nested themes
+
+ThemeProviders can be nested to create theme overrides for specific sections.
+
+```jsx
+<ThemeProvider theme={defaultTheme} activeColorScheme="light">
+  {/* Default theme in light color scheme */}
+
+  <ThemeProvider theme={customTheme} activeColorScheme="dark">
+    {/* Custom theme in dark color scheme */}
+  </ThemeProvider>
+</ThemeProvider>
+```
+
+When nesting, you may want to override specific color values from the current theme. Overrides must be conditionally applied because we don't enforce that a theme has both light and dark colors defined.
+
+```jsx
+// Override parts of the parent theme
+const theme = useTheme();
+const customTheme = {
+  ...theme,
+  ...(theme.lightColor &&
+    theme.lightSpectrum && {
+      lightColor: {
+        ...theme.lightColor,
+        bg: `rgb(${theme.lightSpectrum.orange50})`,
+        bgPrimary: `rgb(${theme.lightSpectrum.red20})`,
+        bgSecondary: `rgb(${theme.lightSpectrum.blue50})`,
+      },
+    }),
+  ...(theme.darkColor &&
+    theme.darkSpectrum && {
+      darkColor: {
+        ...theme.darkColor,
+        bg: `rgb(${theme.darkSpectrum.orange50})`,
+        bgPrimary: `rgb(${theme.darkSpectrum.red20})`,
+        bgSecondary: `rgb(${theme.darkSpectrum.blue50})`,
+      },
+    }),
+} as const satisfies Theme;
+```
+
+#### Theme inheritence
+
+Nested ThemeProviders do not automatically inherit the theme from their parent provider. You can manually inherit the theme with the `useTheme` hook.
+
+```jsx
+const Example = () => {
+  // Pass the parent theme down to another ThemeProvider
+  const theme = useTheme();
+  return (
+    <ThemeProvider theme={theme} activeColorScheme={theme.activeColorScheme}>
+      {children}
+    </ThemeProvider>
+  );
+};
+```
+
+#### InvertedThemeProvider component
+
+The InvertedThemeProvider automatically inherits from its parent theme and flips the `activeColorScheme` to the opposite value.
+
+```jsx
+<ThemeProvider theme={defaultTheme} activeColorScheme="light">
+  {/* Default theme in light color scheme */}
+
+  <InvertedThemeProvider>
+    {/* Default theme in inverse (dark) color scheme */}
+  </InvertedThemeProvider>
+</ThemeProvider>
+```
+
+### `ThemeConfig` vs `Theme` type
+
+Use the `ThemeConfig` type when creating a theme, or when passing the `theme` prop to the ThemeProvider.
+
+Use the `Theme` type for the return value of the `useTheme` hook. The `Theme` type includes all the properties of `ThemeConfig` - plus the `activeColorScheme`, `color`, and `spectrum` properties.
+
+[See the `ThemeConfig` type definition here &rarr;](https://github.com/coinbase/cds/blob/master/packages/mobile/src/core/theme.ts#L11)
+
+[See the `Theme` type definition here &rarr;](https://github.com/coinbase/cds/blob/master/packages/mobile/src/core/theme.ts#L50)
+
+:::tip
+Although the `Theme` type includes extra properties, you can still pass the `useTheme` return value directly to the ThemeProvider `theme` prop as shown in the [theme inheritence section.](#theme-inheritence)
+:::
+
+### `spectrum` vs `color` values
+
+The `spectrum` variables are partial `"r,g,b"` strings while `color` variables are complete CSS color values.
+
+Both `color` and `spectrum` behave inversely in light and dark mode.
+
+For example with the `defaultTheme` config, `spectrum.gray0` is white in light mode and black in dark mode. We use `spectrum` variables to define `color` variables, so this same behavior extends to `color`.
+
+The `color` variables have semantic names which describe their application in the UI. You should prefer to use `color` variables instead of `spectrum` variables when styling UI.
+
+```jsx
+const theme = useTheme();
+theme.lightSpectrum.gray0; // "255,255,255"
+theme.darkSpectrum.gray0; // "10,11,13"
+theme.spectrum.gray100; // "255,255,255" or "10,11,13", depends on activeColorScheme
+theme.lightColor.bg; // "rgb(255,255,255)"
+theme.darkColor.bg; // "rgb(10,11,13)"
+theme.color.bg; // "rgb(255,255,255)" or "rgb(10,11,13)", depends on activeColorScheme
+```
+
+:::tip
+Prefer to use semantic `color` variables for UI styles. Direct usage of `spectrum` values should be a rare exception.
+:::
+
+### Creating a theme
+#### Defining colors
+
+We recommend defining `lightSpectrum` and `darkSpectrum` as separate objects. This makes it easier to reference them when defining the `lightColor` and `darkColor` values.
+
+The `lightColor` and `darkColor` values must be raw color strings (hex, rgba, hsl, etc), they cannot contain CSS Variables or CSS functions.
+
+#### The `space` scale
+
+CDS expects that the theme `space` values will be multiples of some base number.
+
+For example, the `defaultTheme` uses `8px` as the base number:
+
+```jsx
+theme.space[0]; // 0
+theme.space[0.25]; // 2
+theme.space[0.5]; // 4
+theme.space[1]; // 8
+theme.space[1.5]; // 12
+theme.space[2]; // 16
+theme.space[3]; // 24
+// etc.
+```
+
+While it is possible to customize the `space` values in any way, deviating from this expectation may produce broken styles.
+
+#### Example new theme
+
+In this example we'll start with the `defaultTheme` and customize a couple values.
+
+```tsx
+import type { ThemeConfig } from '@coinbase/cds-mobile/core/theme';
+import { ThemeProvider } from '@coinbase/cds-mobile/system/ThemeProvider';
+import { defaultTheme } from '@coinbase/cds-mobile/themes/defaultTheme';
+
+// Define lightSpectrum and darkSpectrum as separate objects
+const lightSpectrum = {
+  ...defaultTheme.lightSpectrum,
+  blue60: '8,90,255',
+};
+
+const darkSpectrum = {
+  ...defaultTheme.darkSpectrum,
+  blue60: '65,125,245',
+};
+
+// Use lightSpectrum and darkSpectrum to define the lightColor and darkColor values
+const myTheme = {
+  ...defaultTheme,
+  id: 'my-custom-theme',
+  lightSpectrum,
+  darkSpectrum,
+  lightColor: {
+    ...defaultTheme.lightColor,
+    bgPrimary: `rgb(${lightSpectrum.red60})`,
+  },
+  darkColor: {
+    ...defaultTheme.darkColor,
+    bgPrimary: `rgb(${darkSpectrum.red60})`,
+  },
+} as const satisfies ThemeConfig;
+
+const App = () => (
+  <ThemeProvider theme={myTheme} activeColorScheme="light">
+    {/* Your app components */}
+  </ThemeProvider>
+);
+```
+
+:::tip
+Use the `ThemeConfig` type with TypeScript's `satisfies` keyword to enforce type safety for your theme.
+:::
+
+### `defaultTheme` config
+
+The `defaultTheme` is a good example of a complete `ThemeConfig`. You can use it as an example when developing your own themes.
+
+[See the `defaultTheme` source code here &rarr;](https://github.com/coinbase/cds/blob/master/packages/mobile/src/themes/defaultTheme.ts)
+
+<JSONCodeBlock json={defaultTheme} />
+
+### `ThemeVars` namespace
+
+The `ThemeVars` namespace contains type definitions for all themeable variable names in CDS. It includes any custom theme variables added in `ThemeVarsExtended`.
+
+```tsx
+import type { ThemeVars } from '@coinbase/cds-common/core/theme';
+
+// All theme variables are accessible through ThemeVars
+ThemeVars.Color; // 'fg' | 'bg' | 'bgPrimary' | 'bgSecondary' | ...
+ThemeVars.SpectrumColor; // 'blue60' | 'red40' | 'gray100' | ...
+ThemeVars.SpectrumHue; // 'blue' | 'green' | 'orange' | 'gray' | ...
+ThemeVars.SpectrumHueStep; // 0 | 5 | 10 | 20 | ...
+ThemeVars.Space; // 0 | 0.25 | 0.5 | 1 | 2 | ...
+ThemeVars.BorderWidth; // 0 | 100 | 200 | ...
+ThemeVars.BorderRadius; // 0 | 100 | 200 | ...
+ThemeVars.Font; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.FontFamily; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.FontSize; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.FontWeight; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.LineHeight; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.TextTransform; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.IconSize; // 'xs' | 's' | 'm' | 'l'
+ThemeVars.AvatarSize; // 's' | 'm' | 'l' | 'xl' | ...
+ThemeVars.ControlSize; // 'checkboxSize' | 'radioSize' | ...
+```
+
+### Extending the theme
+
+You can extend the theme by adding custom theme variables. In this example we'll show how to add a custom color variable, but you can extend other types of `ThemeVars` as well.
+
+Start by overriding interfaces in the `ThemeVarsExtended` namespace to add new theme variables. Only the key names are used, the `void` type is just a necessary placeholder.
+
+```jsx
+declare module '@coinbase/cds-common/core/theme' {
+  export namespace ThemeVarsExtended {
+    export interface Color {
+      myCustomColor: void;
+    }
+  }
+}
+```
+
+This adds `myCustomColor` to `ThemeVars.Color` - which enforces that this variable must be defined in your theme to satisfy the `ThemeConfig` type, and allows this variable name to be passed to the `StyleProps` API anywhere that theme colors are accepted.
+
+Now that `myCustomColor` is defined in your theme the `useTheme` hook will include it in the return value.
+

package/mcp-docs/mobile/hooks/useDimensions.txt

@@ -0,0 +1,72 @@
+# useDimensions
+
+Measures the screen dimensions and status bar height.
+
+## Import
+
+```tsx
+import { useDimensions } from '@coinbase/cds-mobile/hooks/useDimensions'
+```
+
+## API
+
+### Parameters
+
+None. The hook takes no parameters.
+
+### Returns
+
+Returns an object with the following properties:
+
+```tsx
+type Return = {
+  screenHeight: number;
+  screenWidth: number;
+  statusBarHeight: number;
+};
+```
+
+- `screenHeight`: The total height of the device screen in points (DIP).
+- `screenWidth`: The total width of the device screen in points (DIP).
+- `statusBarHeight`: The height of the device's status bar in points (DIP).
+
+:::tip
+All dimensions are in points (DIP - Density Independent Pixels), not physical pixels. Values automatically update on device orientation changes. The status bar height varies by device type, orientation, and presence of notches or dynamic islands.
+:::
+
+## Examples
+
+### Basic usage
+
+```tsx
+function Example() {
+  const { screenWidth, screenHeight, statusBarHeight } = useDimensions();
+
+  return (
+    <Box backgroundColor="bgAlternate" padding={3} borderRadius={300} width="100%">
+      <VStack gap={2}>
+        <TextHeadline>
+          Screen dimensions: {screenWidth}x{screenHeight}
+        </TextHeadline>
+        <TextHeadline>Status bar height: {statusBarHeight}px</TextHeadline>
+      </VStack>
+    </Box>
+  );
+}
+```
+
+### With Safe Area Layout
+
+```tsx
+function Example() {
+  const { screenHeight, statusBarHeight } = useDimensions();
+  const contentHeight = screenHeight - statusBarHeight;
+
+  return (
+    <Box backgroundColor="bgAlternate" height={contentHeight} paddingTop={statusBarHeight}>
+      <TextHeadline>Content below status bar</TextHeadline>
+    </Box>
+  );
+}
+```
+