菜单
Storybook patterns for Drupal Single Directory Components (SDC). Covers atomic design hierarchy, story organization, naming conventions, controls matching component props, structural testing via stories, page stories as regression references, and asset handling.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | drupal-storybook |
| description | Storybook patterns for Drupal Single Directory Components (SDC). Covers atomic design hierarchy, story organization, naming conventions, controls matching component props, structural testing via stories, page stories as regression references, and asset handling. |
Stories prove your components work. They are living documentation, visual regression references, and the first place structural problems become visible. A story that renders correctly with realistic content gives confidence; a story that only works with placeholder text hides structural gaps.
Stories fall into a few categories:
Stories are organized by atomic design level:
| Level | Location | Examples |
|---|---|---|
| Atoms | stories/atoms/ | button, heading, text, image, logo, icon |
| Molecules | stories/molecules/ | card, blockquote, breadcrumb, search-form |
| Organisms | stories/organisms/ | hero, card-grid, two-column-text, stats-banner, header, footer, navigation |
<component-name>.stories.tsx using kebab-caseAtoms/Button, Molecules/Card, Organisms/HeroAuto documentation should be used, and all parameter types must be explicitly defined with appropriate controls. Always cross-reference the story parameters with the SDC *.component.yml props and slots. See references/sdc-component-yml.md for the full schema.
Non-interactive tests (e.g. expects) can be added to component stories, but interactive tests that simulate user input MUST NOT be included in stories.
Both props and slots arguments MUST be either scalar values, an image object type, or a React/Twig fragment of public components. You must never use direct HTML markup in story arguments.
Every prop defined in the component's *.component.yml should have a matching Storybook argType. Use the JSON Schema type to pick the right control:
| JSON Schema type | Storybook control |
|---|---|
type: string | text |
type: string + enum | select or radio |
type: boolean | boolean |
type: integer / type: number | number |
type: array | object (JSON editor) |
type: object | object (JSON editor) |
For slots defined in *.component.yml, represent them as render-function args or children in JSX. Document which slot each arg maps to.
stories/tests/<component-name>.stories.tsx using kebab-case, although if a component has a large number of tests, they can be grouped using <component-name>-<group>.stories.tsx.These are intended to provide automated tests for components and other UI elements.
Auto documentation MUST be disabled.
stories/templates/Templates/stories/pages/<page-name>.stories.tsx using kebab-case.Pages/These provide an example of how a page could be built using components.
Autodocs must be disabled and the fullscreen layout must be used. There must only be one story per page.
A layout wrapper component from the templates stories should be used to ensure consistent wrapping of the page with header, footer, and navigation.
Both props and slots arguments MUST be either scalar values, an image object type, or a React/Twig fragment of public components. You must never use direct HTML markup.
Placehold.co can be used to generate placeholder images for components:
{
src: "https://placehold.co/800x600",
alt: "Example image placeholder",
width: 800,
height: 600,
}
Page stories MUST only import and compose existing components.
themes/custom/mytheme/components/<name>)<div>, <span>, <section>) for layoutIf you need a wrapper <div>, find the existing component that provides that layout (e.g., a section component for width constraints, a grid component for columns). If none exists, create the SDC component first.
Control spacing between components using a spacing or layout component, NOT margins, padding, or wrapper divs.
// Correct — use a layout component
<Hero title="About Us" />
<Section width="normal" content={<Text text="<p>Our story...</p>" />} />
// Wrong — raw HTML and className for spacing
<Hero title="About Us" />
<div className="mt-16">
<Section width="normal" content={<Text text="<p>Our story...</p>" />} />
</div>
Page stories should export only ONE story (typically Default) with a name property matching the page title. This creates flat sidebar navigation instead of nested folders.
export const Default: Story = {
name: 'Home Page',
render: () => (
<PageWrapper>
<Hero title="Welcome" />
<Section width="normal" content={<Text text="<p>...</p>" />} />
</PageWrapper>
),
};
Every key page should have a corresponding page story that serves as a visual regression reference.
text: "Footer" instead of 3 menu columns with social links, it will not catch a structurally inadequate footer component.Stories are the first line of defense -- if a component crashes in Storybook, it will crash on the live site.
npm run build-storybook (Storybook static build) fails, fix before deploying.Assets should be stored in a stories/assets/ directory, in suitable subdirectories depending on the scope of the asset. An index.ts file must be created to export the assets with the correct image type. Real assets must never be directly imported in stories without their image type. The image type must include the correct dimensions and provide alt text.
Given a Drupal SDC card component at themes/custom/mytheme/components/card/:
name: Card
status: stable
props:
type: object
required:
- title
properties:
title:
type: string
title: Card title
description:
type: string
title: Card description
image_url:
type: string
title: Image URL
slots:
actions:
title: Card actions
description: Buttons or links at the bottom of the card.
import type { Meta, StoryObj } from '@storybook/react';
import Card from './Card';
const meta: Meta<typeof Card> = {
title: 'Molecules/Card',
component: Card,
tags: ['autodocs'],
argTypes: {
title: { control: 'text' },
description: { control: 'text' },
image_url: { control: 'text' },
},
};
export default meta;
type Story = StoryObj<typeof Card>;
// Bare minimum — no props, verifies component does not crash with empty data.
export const Empty: Story = {};
// Full realistic content — verifies all structural elements render.
export const FullContent: Story = {
args: {
title: 'Annual Community Report',
description: 'A detailed overview of our community impact this year.',
image_url: 'https://placehold.co/400x300',
},
};
See references/sdc-component-yml.md for the complete *.component.yml schema, including dependencies, libraryOverrides, and advanced prop patterns.
Use when reviewing Drupal code for standards compliance across PHP, JavaScript, CSS, Twig, YAML, SQL, and markup — dynamically loads relevant standards per file type using Drupal's official community guidelines.
How to write, modify, and style React components for Drupal Canvas and Drupal CMS. Covers the technology stack (React 19, Tailwind CSS 4, CVA variants, cn utility), component.yml prop and slot definitions, enum naming, image and video prop types, formatted text fields, color scheme variants, theme tokens from global.css, required folder structure (index.jsx + component.yml), and matching source site visual styles including extracting design tokens, dark backgrounds, gradient text, glass/blur effects, and updating global.css theme. Use when building, editing, or fixing any component in src/components/.
Managing content in Drupal CMS via JSON:API. Covers listing, fetching, creating, updating, and deleting pages and content entities using npm run content commands. Includes page component structure (uuid, component_id, inputs, parent_uuid, slot), image uploading and media target_id handling, formatted HTML text fields, UUID generation, input format reference mapping component.yml prop types to JSON formats, menu item listing (menu_items--main, menu_items--footer, menu_items--social-media are read-only via API — must use admin UI for create/update/delete), page path alias management, and common pitfalls like wrong media IDs, link props as objects instead of strings, plain strings for HTML fields, target_id as integer instead of string, langcode errors, and JSON:API read-only mode. Use when composing pages, adding components to pages, uploading images, or interacting with the Drupal CMS content API.
Search and fetch Canvas and Drupal CMS documentation pages. Takes a query describing what you need to know (e.g., "code components", "page regions", "known issues", "data fetching") and returns the full content of matching documentation pages. Invoke with /canvas-docs-explorer <query>. Use this whenever you need to understand how Canvas or Drupal CMS works, verify platform behavior, check for limitations, or find configuration options.
Use when setting up a new Drupal CMS project with Canvas for component development. Covers DDEV, JSON:API write mode, Canvas OAuth client, permissions, page regions, menus, project scaffolding, .env, CSS layer fix, and Storybook validation. Every step is idempotent — safe to re-run.
Step-by-step guide for scaffolding a new React component from scratch. Covers copying an existing component as a base, creating the required index.jsx and component.yml files, naming conventions (snake_case machineName, no project prefixes), creating the matching Storybook story file, reusing existing components via imports, composability patterns, and internal component setup (status false). Use when a needed component does not yet exist in src/components/ and must be created.