@primer/react-brand 0.69.1-rc.0a4e5ff5 → 0.70.0-rc.138127ad

package/docs/components/CTABanner/react.md

@@ -0,0 +1,343 @@
+---
+title: CTA banner
+description: Use the CTA banner component to highlight and create urgency around user actions.
+keywords: ['call to action', 'banner', 'conversion', 'highlight', 'urgent']
+ready: true
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=539%3A14285&t=RJEWZhVUtrRQ0pKh-0
+source: https://github.com/primer/brand/blob/main/packages/react/src/CTABanner/CTABanner.tsx
+storybook: '/brand/storybook/?path=/story/components-ctabanner--playground'
+---
+
+```js
+import {CTABanner, Button} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<CTABanner>
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### Variants
+
+#### Balanced
+
+> A `CTABanner.Image` child is required in this variant.
+
+```jsx
+<CTABanner variant="balanced">
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+  <CTABanner.Image src="/images/placeholder.png" alt="placeholder" />
+</CTABanner>
+```
+
+#### Minimal
+
+> `CTABanner.Image` is not supported in this variant and will not be rendered.
+
+```jsx
+<CTABanner variant="minimal">
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### With logo
+
+Use `CTABanner.Logo` to display a brand mark above the heading.
+
+```jsx
+<CTABanner>
+  <CTABanner.Logo>
+    <svg role="img" focusable="false" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 45 16" width="45" height="16">
+      <title>GitHub</title>
+      <path d="M8.81 7.35v5.74c0 .04-.01.11-.06.13 0 0-1.25.89-3.31.89-2.49 0-5.44-.78-5.44-5.92S2.58 1.99 5.1 2c2.18 0 3.06.49 3.2.58.04.05.06.09.06.14L7.94 4.5c0 .09-.09.2-.2.17-.36-.11-.9-.33-2.17-.33-1.47 0-3.05.42-3.05 3.73s1.5 3.7 2.58 3.7c.92 0 1.25-.11 1.25-.11v-2.3H4.88c-.11 0-.19-.08-.19-.17V7.35c0-.09.08-.17.19-.17h3.74c.11 0 .19.08.19.17Zm35.85 2.33c0 3.43-1.11 4.41-3.05 4.41-1.64 0-2.52-.83-2.52-.83s-.04.46-.09.52c-.03.06-.08.08-.14.08h-1.48c-.1 0-.19-.08-.19-.17l.02-11.11c0-.09.08-.17.17-.17h2.13c.09 0 .17.08.17.17v3.77s.82-.53 2.02-.53l-.01-.02c1.2 0 2.97.45 2.97 3.88ZM27.68 2.43c.09 0 .17.08.17.17v11.11c0 .09-.08.17-.17.17h-2.13c-.09 0-.17-.08-.17-.17l.02-4.75h-3.31v4.75c0 .09-.08.17-.17.17h-2.13c-.08 0-.17-.08-.17-.17V2.6c0-.09.08-.17.17-.17h2.13c.09 0 .17.08.17.17v4.09h3.31V2.6c0-.09.08-.17.17-.17Zm8.26 3.64c.11 0 .19.08.19.17l-.02 7.47c0 .09-.06.17-.17.17H34.6c-.07 0-.14-.04-.16-.09-.03-.06-.08-.45-.08-.45s-1.13.77-2.52.77c-1.69 0-2.92-.55-2.92-2.75V6.25c0-.09.08-.17.17-.17h2.14c.09 0 .17.08.17.17V11c0 .75.22 1.09.97 1.09s1.3-.39 1.3-.39V6.26c0-.11.06-.19.17-.19Zm-17.406 5.971h.005a.177.177 0 0 1 .141.179v1.5c0 .07-.03.14-.09.16-.1.05-.74.22-1.27.22-1.16 0-2.86-.25-2.86-2.69V8.13h-1.11c-.09 0-.17-.08-.17-.19V6.58c0-.08.05-.15.13-.17.07-.01 1.16-.28 1.16-.28V3.96c0-.08.05-.13.14-.13h2.16c.09 0 .14.05.14.13v2.11h1.59c.08 0 .16.08.16.17v1.7c0 .11-.07.19-.16.19h-1.59v3.131c0 .47.27.83 1.05.83.247 0 .481-.049.574-.05ZM12.24 6.06c.09 0 .17.08.17.17v7.37c0 .18-.05.27-.25.27h-1.92c-.17 0-.3-.07-.3-.27V6.26c0-.11.08-.2.17-.2Zm29.99 3.78c0-1.81-.73-2.05-1.5-1.97-.6.04-1.08.34-1.08.34v3.52s.49.34 1.22.36c1.03.03 1.36-.34 1.36-2.25ZM11.19 2.68c.75 0 1.36.61 1.36 1.38 0 .77-.61 1.38-1.36 1.38-.77 0-1.38-.61-1.38-1.38 0-.77.61-1.38 1.38-1.38Zm7.34 9.35v.001l.01.01h-.001l-.005-.001v.001c-.009-.001-.015-.011-.024-.011Z"></path>
+    </svg>
+  </CTABanner.Logo>
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### With link
+
+Use `CTABanner.Link` to provide a secondary call-to-action as a text link instead of a button.
+
+```jsx
+<CTABanner>
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id.
+  </CTABanner.Description>
+  <CTABanner.Link href="#">Read the customer story</CTABanner.Link>
+</CTABanner>
+```
+
+### Duotone heading text
+
+Wrap part of a heading in a `<b>` tag to apply the duotone emphasis color.
+
+```jsx
+<CTABanner>
+  <CTABanner.Heading>
+    Where the most ambitious teams <b>build great things</b>
+  </CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### Alignment
+
+The content alignment can be changed using the `align` prop on the root `CTABanner`. This can be configured to either `start` or `center`.
+
+```jsx
+<CTABanner align="center">
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### Optional background image
+
+```jsx
+<ThemeProvider colorMode="dark">
+  <CTABanner
+    backgroundImageSrc={{
+      narrow: 'https://github.com/user-attachments/assets/a28110fd-d019-41a4-8f80-b49ae8895708',
+      regular: 'https://github.com/user-attachments/assets/a28110fd-d019-41a4-8f80-b49ae8895708',
+      wide: 'https://github.com/user-attachments/assets/a28110fd-d019-41a4-8f80-b49ae8895708',
+    }}
+    align="center"
+    hasShadow={false}
+  >
+    <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+    <CTABanner.Description variant="default">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+      felis nam pulvinar risus elementum.
+    </CTABanner.Description>
+    <CTABanner.ButtonGroup>
+      <Button>Primary Action</Button>
+    </CTABanner.ButtonGroup>
+  </CTABanner>
+</ThemeProvider>
+```
+
+### Optional background colors
+
+`CTABanner` supports `default`, `subtle` and arbitrary `background-color` values
+
+```jsx
+<CTABanner backgroundColor="subtle" hasShadow={false}>
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### Optional border
+
+A border can be provided using the `hasBorder` prop on the root `CTABanner`. This will render a border around the `CTABanner` component giving further separation between the foreground and background. Especially when there is no shadow present on the background.
+
+```jsx
+<CTABanner hasBorder>
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### Optional background
+
+A background can be removed using the `hasBackground` prop on the root `CTABanner`. This will render the `CTABanner` component without a background allowing it to blend in with its parent.
+
+```jsx
+<CTABanner hasBackground={false} hasShadow={false}>
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### Remove shadow
+
+The shadow can be removed using the `hasShadow` prop. This will render the component without the background shadow.
+
+```jsx
+<CTABanner hasShadow={false}>
+  <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+  <CTABanner.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </CTABanner.Description>
+  <CTABanner.ButtonGroup>
+    <Button>Primary Action</Button>
+    <Button>Secondary Action</Button>
+  </CTABanner.ButtonGroup>
+</CTABanner>
+```
+
+### Shadow color customization
+
+The default shadow colors can be customized through their respective CSS variables.
+
+```jsx filename="noinline"
+const App = () => {
+  const designTokenOverrides = `
+  .custom-colors[data-color-mode='dark'] {
+    /*
+     * Modify the value of these tokens.
+     * Remember to apply light mode equivalents if you're enabling theme switching.
+     */
+    --brand-CTABanner-shadow-color-start: var(--base-color-scale-purple-5);
+    --brand-CTABanner-shadow-color-end: var(--base-color-scale-red-5);
+  }
+`
+  return (
+    <ThemeProvider colorMode="dark" className="custom-colors">
+      <style>{designTokenOverrides}</style>
+      <CTABanner>
+        <CTABanner.Heading>Where the most ambitious teams build great things</CTABanner.Heading>
+        <CTABanner.Description>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed
+          turpis felis nam pulvinar risus elementum.
+        </CTABanner.Description>
+        <CTABanner.ButtonGroup>
+          <Button>Primary Action</Button>
+          <Button>Secondary Action</Button>
+        </CTABanner.ButtonGroup>
+      </CTABanner>
+    </ThemeProvider>
+  )
+}
+render(<App />)
+```
+
+## Component props
+
+### CTABanner `Required`
+
+| name                      | type                                                   | default     | required | description                                                       |
+| ------------------------- | ------------------------------------------------------ | ----------- | -------- | ----------------------------------------------------------------- |
+| `children`                | `ReactNode`, `ReactNode[]`                             | `undefined` | `true`   | Content to include within the banner component                    |
+| `variant`                 | `'default' \| 'balanced' \| 'minimal'`                 | `'default'` | `false`  | Alternative layout presentations                                  |
+| `align`                   | `'start' \| 'center'`                                  | `'center'`  | `false`  | The horizontal positioning of content within the banner component |
+| `backgroundColor`         | `'default' \| 'subtle' \| 'string' \| 'ResponsiveMap'` | `'default'` | `false`  | Optional, custom background color                                 |
+| `backgroundImageSrc`      | `'string' \| 'ResponsiveMap'`                          | `undefined` | `false`  | Optional, custom background image                                 |
+| `backgroundImagePosition` | `'string' \| 'ResponsiveMap'`                          | `'center'`  | `false`  | Optional, custom background position                              |
+| `backgroundImageSize`     | `'string' \| 'ResponsiveMap'`                          | `'cover'`   | `false`  | Optional, custom background position size                         |
+| `hasBorder`               | `boolean`                                              | `false`     | `false`  | A flag used to provide a border to the banner component           |
+| `hasGridLines`            | `boolean`                                              | `false`     | `false`  | Enables optional gridlines appearance                             |
+| `hasShadow`               | `boolean`                                              | `false`     | `false`  | A flag used to provide a shadow to the banner component           |
+| `hasBackground`           | `boolean`                                              | `true`      | `false`  | A flag used to add a background to the banner component           |
+
+### CTABanner.Heading
+
+| name       | type                                           | default     | required | description                                                                                                                  |
+| ---------- | ---------------------------------------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `children` | `ReactNode`, `ReactNode[]`                     | `undefined` | `true`   | Content to be displayed inside the `CTABanner.Heading` component. Wrap text in `<b>` to apply duotone emphasis.              |
+| `as`       | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h3'`      | `false`  | Heading level                                                                                                                |
+| `size`     | `'1' \| '2' \| '3' \| '4' \| '5' \| '6'`       | `'3'`       | `false`  | Visual heading size, irrespective of level. Note: the `minimal` variant defaults the visual size to `'6'` when not provided. |
+
+### CTABanner.Description
+
+| name       | type                               | default     | required | description                                         |
+| ---------- | ---------------------------------- | ----------- | -------- | --------------------------------------------------- |
+| `children` | `ReactNode`, `ReactNode[]`         | `undefined` | `true`   | Content to be displayed inside the banner component |
+| `variant`  | `'default' \| 'muted' \| 'subtle'` | `'muted'`   | `false`  | Specify alternative text appearance                 |
+
+### CTABanner.ButtonGroup `Required`
+
+| name         | type                     | default     | required | description                                  |
+| ------------ | ------------------------ | ----------- | -------- | -------------------------------------------- |
+| `children`   | `<Button>`, `<Button>[]` | `undefined` | `true`   | The buttons to be displayed within the group |
+| `buttonSize` | `'medium'`, `'large'`    | `large`     | `false`  | The size of the buttons in the group         |
+| `buttonsAs`  | `'a'`, `'button'`        | `'button'`  | `false`  | Sets underlying HTML element for each button |
+
+`id`, `className` and `ref` are forwarded by default to all children.
+
+### CTABanner.Image
+
+| name  | type     | default     | required | description                               |
+| ----- | -------- | ----------- | -------- | ----------------------------------------- |
+| `src` | `string` | `undefined` | `true`   | The image source URL                      |
+| `alt` | `string` | `undefined` | `true`   | Accessible alternative text for the image |
+
+### CTABanner.Logo
+
+| name       | type        | default     | required | description                                                                           |
+| ---------- | ----------- | ----------- | -------- | ------------------------------------------------------------------------------------- |
+| `children` | `ReactNode` | `undefined` | `true`   | The logo to display, typically an inline SVG so it can be styled and stay accessible. |
+
+### CTABanner.Link
+
+| name       | type                    | default     | required | description                                           |
+| ---------- | ----------------------- | ----------- | -------- | ----------------------------------------------------- |
+| `children` | `ReactNode`             | `undefined` | `true`   | The link text                                         |
+| `href`     | `string`                | `undefined` | `true`   | The link target URL                                   |
+| `variant`  | `'default'`, `'accent'` | `'accent'`  | `false`  | Visual variant. Defaults to `accent` inside CTABanner |
+
+## Related components
+
+- [BreakoutBanner](../BreakoutBanner/index.md)

package/docs/components/CTAForm/index.md

@@ -0,0 +1,95 @@
+---
+title: CTA form
+description: Use CTA form to capture user input and call to action button.
+keywords: ['call to action', 'form', 'input']
+---
+
+## Anatomy
+
+![An image displaying a the CTA form anatomy, with a label on top of an input form, followed by a CTA button and optional checkbox underneath the input.](https://github.com/primer/brand/assets/6951037/d018c27f-847d-4011-b920-d15acb1e5efc)
+
+- Label: Short text that describes the required input form.
+- Text input: Single-line text field
+- Action: Call-to-action button that corresponds after completing the input form.
+- Checkbox: An optional checkbox to request additional behavior.
+
+## Usage
+
+The CTA form is designed to capture user input and call to actions on a website. It serves as an efficient tool to prompt user engagement and action. While it can be placed throughout the page, it is encouraged to be positioned at the bottom to conclude the user journey, summarize key information, and encourage users to take action.
+
+The CTA form presents a concise label, prompting users to provide specific input in the form field. Once users enter the required information, they can trigger the call-to-action through the button. Additionally, the CTA form supports an optional checkbox to seek additional user behavior or acknowledge certain terms.
+
+By adopting the same guidelines as the respective [text input](../../forms/TextInput/index.md) component, [button](../Button/index.md) component, and [checkbox](../../forms/Checkbox/index.md) component, the CTA form ensures consistency in design and enhances user familiarity with the interface.
+
+We recommend the CTA form over the [CTA banner](../CTABanner/index.md) when the main action for a user to take is to submit a form (e.g subscribe to a newsletter) vs taking actions (sign in or bring the user to a pricing page).
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/220b211e-f61f-4afb-83de-6a58980cdd6f)
+
+_Place the CTA form near the end of the page to conclude the user journey and encourage users to take action._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/3f202055-75ae-44be-82ca-f5388d0d3a1c)
+
+_Don't place the CTA Form early on in the user journey. Use the Hero instead for early on._
+
+### Setting Context
+
+Keep the CTA Form simple and intuitive to minimize friction and encourage user engagement. Ensure there is enough context surrounding the component. Utilize the label as a description of the form input.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/04aeb96e-2c24-413e-94be-3608a0e41ec7)
+
+_Include context in areas surrounding the CTA Form to encourage user engagement._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/f0daf653-30ef-42d1-afac-354959c112c7)
+
+_Don't use the CTA Form without context. The label should be used to describe the input, not to provide context._
+
+### Component length
+
+When implementing CTA form, it's important to consider the length of the input field in order to maintain consistency and enhance user familiarity with the interface. Keeping the string length (width) of the component relative to the expected input is a recommended practice. Pair the component with additional information or context instead of spanning in wide viewports.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/ba970b9c-cef8-4cf3-987f-15a11d6e27d2)
+
+_Keep the string length (width) of the component relative to the expected input._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/199c7caa-e605-4f53-9f41-e3d2460f7c55)
+
+_Don't over extend or compress the CTA form when possible._
+
+## Options
+
+### Checkbox
+
+Use the checkbox property in the CTA form to prompt additional user behavior or seek acknowledgment– examples include to gather consent, confirm agreement to terms, or request optional actions.
+
+It is crucial to provide a clear description of the checkbox's purpose and hyperlink to relevant resources. When using the checkbox, completion of the checkbox must be a requirement (not optional) to proceed with the CTA.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/0db61c2b-ad25-4dee-9c6f-eea294315d22)
+
+_Use short and concise text for the checkbox and inline links to relevant resources._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/59f8566f-8679-46b3-8b10-148c9fec104a)
+
+_Don't use lengthy text or unstlyed links._
+
+## Related components
+
+- [Button](../Button/index.md): To display a button that performs an action.
+- [Text input](../../forms/TextInput/index.md): To create an input form for single-line text field.
+- [Checkbox](../../forms/Checkbox/index.md): To select options or acknowledge information.
+- [CTA Banner](../CTABanner/index.md): To draw attention to or create urgency around a user action.

package/docs/components/CTAForm/react.md

@@ -0,0 +1,103 @@
+---
+title: CTA form
+description: Use the CTA form component to create a form that is used to collect minimal information from users.
+keywords: ['call to action', 'form', 'input']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/CTAForm/CTAForm.tsx
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1377%3A30754'
+storybook: '/brand/storybook/?path=/story/components-ctaform--playground'
+---
+
+```js
+import {CTAForm} from '@primer/react-brand'
+```
+
+## Examples
+
+For simplicity, examples on this page use default browser validation.
+
+Use [`FormControl` validation](../../forms/FormControl/index.md#validation) to display the correct status in accordance with [Primer form guidelines](https://primer.style/product/ui-patterns/forms/#validation).
+
+### Default
+
+```jsx
+<CTAForm>
+  <CTAForm.Input>
+    <FormControl required>
+      <FormControl.Label>Your work email address</FormControl.Label>
+      <TextInput placeholder="email" autoComplete="email" />
+    </FormControl>
+  </CTAForm.Input>
+  <CTAForm.Confirm>
+    <FormControl required>
+      <Checkbox name="confirm" />
+      <FormControl.Label>
+        <Text size="300" variant="muted">
+          I agree to the <InlineLink href="www.github.com">Privacy Policy</InlineLink> and{' '}
+          <InlineLink href="www.github.com">Terms of Service</InlineLink>
+        </Text>
+      </FormControl.Label>
+    </FormControl>
+  </CTAForm.Confirm>
+  <CTAForm.Action>Subscribe</CTAForm.Action>
+</CTAForm>
+```
+
+### Component without confirm block
+
+```jsx
+<CTAForm>
+  <CTAForm.Input>
+    <FormControl required>
+      <FormControl.Label>Your work email address</FormControl.Label>
+      <TextInput placeholder="email" autoComplete="email" />
+    </FormControl>
+  </CTAForm.Input>
+  <CTAForm.Action>Subscribe</CTAForm.Action>
+</CTAForm>
+```
+
+### Using onChange & onSubmit handlers
+
+```jsx
+<CTAForm onSubmit={() => alert('onSubmit event triggered')}>
+  <CTAForm.Input onChange={() => console.log('onChange event triggered')}>
+    <FormControl required>
+      <FormControl.Label>Your work email address</FormControl.Label>
+      <TextInput placeholder="email" autoComplete="email" />
+    </FormControl>
+  </CTAForm.Input>
+  <CTAForm.Action>Subscribe</CTAForm.Action>
+</CTAForm>
+```
+
+## Component props
+
+### CTAForm
+
+| name        | type     | default     | required | description                                                        |
+| ----------- | -------- | ----------- | -------- | ------------------------------------------------------------------ |
+| `action`    | `string` | `undefined` | `false`  | The URL that processes the form submission                         |
+| `method`    | `string` | `undefined` | `false`  | The HTTP method to submit the form with                            |
+| `target`    | `string` | `undefined` | `false`  | Indicates where to display the response after submitting the form. |
+| `className` | `string` | `undefined` | `false`  | Sets a custom class                                                |
+
+Additional props can be passed to the `<form>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) accepted by the `<form>` element.
+
+### CTAForm.Input
+
+| name        | type     | default     | required | description         |
+| ----------- | -------- | ----------- | -------- | ------------------- |
+| `className` | `string` | `undefined` | `false`  | Sets a custom class |
+
+### CTAForm.Confirm
+
+| name        | type     | default     | required | description         |
+| ----------- | -------- | ----------- | -------- | ------------------- |
+| `className` | `string` | `undefined` | `false`  | Sets a custom class |
+
+### CTAForm.Action
+
+| name        | type     | default     | required | description         |
+| ----------- | -------- | ----------- | -------- | ------------------- |
+| `className` | `string` | `undefined` | `false`  | Sets a custom class |

package/docs/components/Card/index.md

@@ -0,0 +1,126 @@
+---
+title: Card
+description: Use the card component to display information in a compact way and link to other internal pages.
+keywords: ['card', 'link', 'summary', 'content', 'information']
+---
+
+![An image showing a card with a Copilot Octicon.](https://github.com/primer/brand/assets/6951037/5bb4e3dd-8f53-44c5-a5ed-987c732eaf8f)
+
+## Usage
+
+Use cards to summarize the central idea behind some content and provide a link to its corresponding detailed resource. It is important to present the information in a concise manner, avoiding lengthy and complex descriptions.
+
+Cards should always be used in groups of two or more related concepts.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/139deb0e-0143-4051-a8c8-49b854b58727)
+
+_Use cards in groups to display related information._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/1f009b98-01b8-4cb3-af30-83ccac31c8c9)
+
+_Don't use isolated cards. Consider using a CTABanner instead._
+
+### Stacked
+
+Cards should be stacked to display a list of items that are related to each other. When displaying a visual asset, ensure it is consistent across all cards to create a visually balanced layout. The visual asset should be the same type for each card, either an icon or an image.
+
+For a better visual experience, we recommend using similar length size for the heading and description in all stacked cards.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/28b8dbfa-9ed5-40ba-b1a3-d501ac3be4b8)
+
+_Use the same type of visual asset for all cards and a similar length size for the content._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/6d494165-312e-4e84-94df-199d1d82fd50)
+
+_Don't use different length sizes for the title or the description._
+
+When using an image as the visual asset, we recommend using the same aspect ratio for all images. This will create a more balanced visual experience.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/1a6decfc-a840-440b-8ec7-bf25b7716711)
+
+_Use the same image ratio and a similar length sizes for the content._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/cffafadf-2e9d-47f0-a6db-6f89fb48fabe)
+
+_Don't use different image ratios and a different length size for the content._
+
+Cards typically appear in groups of three or four in desktop viewports. For smaller viewports, or when more than four cards are needed, we recommend stacking the cards vertically. You can use the [Grid](../../layout/Grid/index.md) or the [Stack](../../layout/Stack/index.md) component to achieve this.
+
+Use center alignment when stacking multiple cards up to a maximum of three. For four (or more) use start alignment.
+
+**✅ Do**
+
+_Use center alignment when presenting up to three cards in single row\._
+
+**❌ Don't**
+
+_Don't use center alignment when presenting more than three cards._
+
+_Video demonstration — see the online docs._
+
+_Stack cards vertically so that the content has enough line length._
+
+## Anatomy
+
+![An image showing the card anatomy with an icon as a visual asset, a heading, a description and a CTA text in a vertical order.](https://github.com/primer/brand/assets/6951037/2ae395d0-227d-4794-8e0b-f709a431e636)
+
+### Visual asset
+
+The visual asset is optional and can be an image or an icon. It can be used to provide a visual cue to the user about the content of the card. To avoid visual noise, we recommend using only one icon or image, but not both in the same card.
+
+![An image showing two cards, one with an Icon and another with an Image as the visual assets options.](https://github.com/primer/brand/assets/6951037/21623e82-2ea5-499a-a78f-82b09915af16)
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/e5494fd3-76b1-45fd-8aa7-4acfe834b159)
+
+_Use only one visual asset per card._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/bc29b10b-ee0b-421d-8bc4-0a95fad3791b)
+
+_Don't use both icon and image as the visual asset._
+
+### Label
+
+The label can be used to indicate the type of content or its status. For example, use it to indicate that the content is `new` or that it is a `beta` feature. The label is optional and can be used along with a visual asset.
+
+![An image showing two cards, one with a Label and another one with Label and Icon.](https://github.com/primer/brand/assets/6951037/3e16bb51-9e19-4a98-a9c2-e289d4bf540c)
+
+### Heading
+
+The heading is the main title of the card. It should be short and concise.
+
+### Description
+
+The description is an optional short text that extends the information provided by the heading.
+
+### Call to action
+
+The call to action label indicates the action or resource the card links to. It defaults to "Learn more".
+
+## Options
+
+### Border
+
+Card offers a variation with a border. Border is disabled by default.
+
+## Related components
+
+- [Pillar](../Pillar/index.md): To display related content with less visual emphasis.
+- [River](../River/index.md): To display a list of content items with a visual asset.
+- [CTABanner](../CTABanner/index.md): To display a single block of content to draw attention or create urgency around a user action.
+- [UnorderedList](../UnorderedList/index.md) or the [OrderedList](../OrderedList/index.md): to display a list of plain content items.