@canonical/code-standards 0.1.0

package/docs/storybook.md

@@ -0,0 +1,413 @@
+# Storybook Standards
+
+Standards for storybook development.
+
+## storybook/documentation/source
+
+Component documentation must primarily come from TSDoc comments on the component signature and props. Storybook docs overrides should only be used when the documentation needs to differ between code and Storybook contexts.
+
+### Do
+
+(Do) Use TSDoc comments for primary documentation.
+```typescript
+
+// ContextualMenu/types.ts
+export interface ContextualMenuProps extends HTMLAttributes<HTMLDivElement> {
+  /** The element that triggers the contextual menu */
+  children: ReactElement;
+  /** The items to display in the contextual menu */
+  items: MenuItem[];
+}
+
+// ContextualMenu/ContextualMenu.tsx
+/**
+ * A wrapper component that adds a contextual menu to its children.
+ * The menu appears when the children are clicked or activated via keyboard.
+ */
+const ContextualMenu = ({
+  children,
+  items,
+}: ContextualMenuProps): ReactElement => {
+  // ...
+};
+```
+
+### Don't
+
+(Don't) Add documentation in Storybook parameters when TSDoc is sufficient.
+```typescript
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        component: "A wrapper component that adds a contextual menu to its children" // Covered in TSDoc
+      }
+    }
+  }
+};
+```
+
+---
+
+## storybook/story/decorator
+
+Decorators must be used to wrap stories in common context providers or layout elements. Decorators should generally be defined in `storybook/decorators.tsx` and be imported as `decorators` in the storybook file. Decorators may be defined inline in story files in limited circumstances when it would be difficult to globally define a semantic decorator (e.g., a decorator that provides mock data specific to that component).
+
+### Do
+
+(Do) Use decorators for static context or layout wrapping.
+```typescript
+
+// storybook/decorators.tsx
+
+export const theme = (Story: StoryFn<typeof Component>) => (
+  <ThemeProvider theme="dark">
+    <Story />
+  </ThemeProvider>
+);
+
+export const config = (Story: StoryFn<typeof Component>) => (
+  <ConfigProvider locale="en">
+    <Story />
+  </ConfigProvider>
+);
+
+// src/ui/<ComponentName>/<ComponentName>.stories.tsx
+
+import * as decorators from "storybook/decorators.js";
+export const WithTheme: Story = {
+  decorators: [decorators.theme],
+  args: {
+    variant: "primary"
+  }
+};
+
+// Component-level decorator in meta, applies to all stories in this file.
+const meta = {
+  decorators: [decorators.config],
+} satisfies Meta<typeof Component>;
+
+export default meta;
+```
+
+### Don't
+
+(Don't) Use function-based stories for static wrapping that could be done with decorators.
+```typescript
+// Bad: Using function-based story for static wrapping
+export const WithTheme = (args: ComponentProps) => (
+  <ThemeProvider theme="dark">
+    <Component {...args} />
+  </ThemeProvider>
+);
+```
+
+---
+
+## storybook/story/documentation
+
+Story documentation must focus on usage patterns and variations, not implementation details. Each story should demonstrate a specific use case or variation.
+
+### Do
+
+(Do) Document usage patterns and variations.
+```typescript
+export const WithCustomTrigger: Story = {
+  args: {
+    trigger: <button>Custom Trigger</button>
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "The component accepts a custom trigger element to replace the default button."
+      }
+    }
+  }
+};
+```
+
+### Don't
+
+(Don't) Document implementation details or internal behavior.
+```typescript
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: "Uses React.createPortal internally to render the popup" // Bad: Implementation detail
+      }
+    }
+  }
+};
+```
+
+---
+
+## storybook/story/format
+
+Stories must use one of three formats, each serving specific needs:
+1. CSF3 (object-based) format must be used for standard component variations where args define the component state.
+2. Function-based format must be used when the story needs to directly control component rendering or wrap the component with custom elements.
+3. Template-based format must be used when multiple stories share the same logic but differ in their args, and the template differs from the component markup.
+
+### Do
+
+(Do) Use the format that matches your specific use case.
+```typescript
+// CSF3: For standard component variations through args
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    variant: "primary",
+    children: "Click me",
+    disabled: false
+  }
+};
+
+// Function-based: When story needs dynamic rendering logic
+export const WithDynamicChildren = (args: ComponentProps) => {
+  const [items] = useState(["Item 1", "Item 2"]);
+  return (
+    <Component {...args}>
+      {items.map((item) => (
+        <ListItem key={item}>{item}</ListItem>
+      ))}
+    </Component>
+  );
+};
+
+// Template-based: When multiple stories share logic
+const Template: StoryFn<typeof Component> = (args) => (
+  <div className="button-container">
+    <Label>Button:</Label>
+    <Component {...args} />
+  </div>
+);
+
+export const Primary = Template.bind({});
+Primary.args = { variant: "primary" };
+```
+
+### Don't
+
+(Don't) Use a format that doesn't match your use case.
+```typescript
+// Bad: Using function format for simple args variation
+export const SimpleButton = () => (
+  <Component variant="primary" disabled={false}>
+    Click me
+  </Component>
+);
+
+// Bad: Duplicating complex logic without template
+export const First: Story = {
+  decorators: [(Story) => (
+    <div className="button-container">
+      <Label>Button:</Label>
+      <Story />
+    </div>
+  )]
+};
+```
+
+---
+
+## storybook/story/import
+
+Stories must import their component as 'Component' to maintain a consistent, generic reference that is decoupled from the specific component name.
+
+### Do
+
+(Do) Import the component generically as 'Component'.
+```typescript
+import Component from "./SkipLink.js";
+
+const meta = {
+  title: "SkipLink",
+  component: Component,
+} satisfies Meta<typeof Component>;
+
+export const Default: Story = {
+  args: {
+    children: "Skip to main content"
+  }
+};
+```
+
+### Don't
+
+(Don't) Import the component using its specific name.
+```typescript
+import SkipLink from "./SkipLink.js";
+
+const meta = {
+  title: "SkipLink",
+  component: SkipLink,  // Bad: Using specific component name
+} satisfies Meta<typeof SkipLink>;
+```
+
+---
+
+## storybook/story/naming
+
+Story names must be descriptive and follow a consistent pattern. Use PascalCase for story exports and natural language for story titles.
+
+### Do
+
+(Do) Use clear, descriptive names that indicate the variation.
+```typescript
+export const WithCustomStyles: Story = {
+  args: {
+    className: "custom",
+    children: "Styled Content"
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Demonstrates custom styling options"
+      }
+    }
+  }
+};
+```
+
+### Don't
+
+(Don't) Use technical or implementation-focused names.
+```typescript
+export const TestCase1: Story = {  // Bad: Non-descriptive name
+  args: {
+    _testFlag: true,  // Bad: Implementation detail
+    children: "Content"
+  }
+};
+```
+
+---
+
+## storybook/story/organization
+
+Stories must be organized into logical groups that demonstrate related features and variations. Each story should focus on a specific use case or feature, with clear naming that indicates what aspect of the component it demonstrates.
+
+### Do
+
+(Do) Group related features with clear, descriptive names.
+```typescript
+// Basic usage
+export const Default: Story = {
+  args: {
+    mainId: "main",
+    children: "Skip to main content"
+  }
+};
+
+// Custom element targeting
+export const CustomMainElement: Story = {
+  args: {
+    mainId: "my-main-element",
+    children: "Skip to main content"
+  }
+};
+
+// Content customization
+export const CustomText: Story = {
+  args: {
+    mainId: "main",
+    children: "Jump to content"
+  }
+};
+```
+
+### Don't
+
+(Don't) Use unclear names or mix unrelated features in a single story.
+```typescript
+// Bad: Unclear what this story demonstrates
+export const Variant1: Story = {
+  args: {
+    mainId: "custom",
+    children: "Skip",
+    className: "special",
+    onClick: () => {},
+    style: { color: "red" }
+  }
+};
+```
+
+---
+
+## storybook/story/testing
+
+Stories that test component behavior must use the `play` function to simulate user interactions and verify expected outcomes.
+
+### Do
+
+(Do) Use play functions to test interactive behavior.
+```typescript
+export const InteractionTest: Story = {
+  args: {
+    children: "Click Me",
+    onClick: () => {}
+  },
+  play: async ({ canvasElement, args }) => {
+    const button = canvasElement.querySelector("button");
+    await userEvent.click(button);
+    await expect(args.onClick).toHaveBeenCalled();
+  }
+};
+```
+
+### Don't
+
+(Don't) Test implementation details or internal state.
+```typescript
+export const InternalTest: Story = {
+  play: async ({ component }) => {
+    // Bad: Testing internal implementation
+    expect(component._internalState).toBe(true);
+  }
+};
+```
+
+---
+
+## storybook/story/visibility
+
+Stories that exist solely for testing or visual coverage but don't represent valid usage patterns must be hidden from documentation and the sidebar using tags.
+
+### Do
+
+(Do) Hide test-only stories that don't represent valid usage.
+```typescript
+export const FocusedState: Story = {
+  args: {
+    isOpen: true,
+    children: "Test Content"
+  },
+  tags: ["!dev", "!autodocs"],
+  play: async ({ canvasElement }) => {
+    const element = canvasElement.querySelector(".component");
+    element.focus();
+  }
+};
+```
+
+### Don't
+
+(Don't) Show implementation details or test states in documentation.
+```typescript
+export const InternalTestState: Story = {
+  args: {
+    _internalProp: true,  // Bad: Exposing internal state
+    children: "Test"
+  },
+  parameters: {
+    docs: {
+      description: { story: "Tests internal state" }  // Bad: Implementation detail
+    }
+  }
+};
+```
+
+---

package/docs/styling.md

@@ -0,0 +1,163 @@
+# Styling Standards
+
+Standards for styling development.
+
+## styling/themes/definition
+
+Themes are collections of semantic tokens that provide consistent styling across components. See css/themes/activation for implementation details.
+
+### Do
+
+(Do) Define a theme as a complete set of semantic tokens.
+```
+{
+  "theme": {
+    "canonical": {
+      "color": {
+        "background": {
+          "default": {
+            "$type": "color",
+        "$value": "{color.neutral.100}"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Don't
+
+(Don't) Mix implementation details into theme definitions.
+```
+{
+  "theme": {
+    "canonical": {
+      "class": "canonical",     // Bad: CSS implementation detail
+      "container": "div",       // Bad: HTML implementation detail
+    }
+  }
+}
+```
+
+---
+
+## styling/tokens/creation
+
+Design tokens must be created for all design decisions in a component. See css/properties/values for how these tokens are used in CSS implementation.
+
+### Do
+
+(Do) Create component tokens that reference semantic tokens for design decisions.
+```
+{
+  "button": {
+    "background": {
+      "$type": "color",
+        "$value": "{color.background.primary}"
+    }
+  }
+}
+```
+
+### Don't
+
+(Don't) Use raw values for design decisions.
+```
+{
+  "button": {
+    "background": {
+      "$type": "color",
+        "$value": "#0066CC"  # Should reference semantic token like {color.background.primary}
+    }
+  }
+}
+```
+
+---
+
+## styling/tokens/scoping
+
+Design tokens must be scoped according to their type:
+- Primitive tokens: Global scope (system-wide base values)
+- Semantic tokens: Theme scope (theme-specific bindings to primitive tokens)
+- Component tokens: Component scope (bindings to semantic tokens)
+
+### Do
+
+(Do) Define primitive tokens in global scope.
+```
+{
+  "color": {
+    "neutral": {
+      "100": {
+        "$type": "color",
+        "$value": "#FFFFFF"
+      }
+    }
+  }
+}
+```
+
+### Don't
+
+(Don't) Define primitive tokens in theme scope.
+```
+{
+  "theme": {
+    "canonical": {
+      "color": {
+        "neutral": {
+          "100": {
+            "$type": "color",
+        "$value": "#FFFFFF"  # Should be defined in global scope
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## styling/tokens/types
+
+Design tokens follow a strict hierarchy:
+      - Primitive tokens: Raw values that form the foundation of the design system
+      - Semantic tokens: Map semantic concepts to primitive token values
+      - Component tokens: Map component properties to semantic token values
+
+### Do
+
+(Do) Define semantic tokens that map to primitive tokens.
+```
+{
+  "color": {
+    "background": {
+      "default": {
+        "$type": "color",
+        "$value": "{color.neutral.100}"
+      }
+    }
+  }
+}
+```
+
+### Don't
+
+(Don't) Skip the semantic layer by mapping component tokens directly to primitives.
+```
+{
+  "button": {
+    "padding": {
+      "vertical": {
+        "$type": "dimension",
+        "$value": "{spacing.unit}"  # Should reference semantic token like {spacing.vertical.medium}
+      }
+    }
+  }
+}
+```
+
+---