@canonical/code-standards 0.1.0 → 0.1.2

package/data/storybook.ttl

@@ -15,9 +15,10 @@ cs:DocumentationSource a cs:CodeStandard ;
     cs:name "storybook/documentation/source" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "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." ;
-    cs:dos """
-(Do) Use TSDoc comments for primary documentation.
-```typescript
+    cs:do [
+        cs:description "Use TSDoc comments for primary documentation." ;
+        cs:language "typescript" ;
+        cs:code """
 
 // ContextualMenu/types.ts
 export interface ContextualMenuProps extends HTMLAttributes<HTMLDivElement> {
@@ -38,11 +39,12 @@ const ContextualMenu = ({
 }: ContextualMenuProps): ReactElement => {
   // ...
 };
-```
-""" ;
-    cs:donts """
-(Don't) Add documentation in Storybook parameters when TSDoc is sufficient.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Add documentation in Storybook parameters when TSDoc is sufficient." ;
+        cs:language "typescript" ;
+        cs:code """
 export const Default: Story = {
   parameters: {
     docs: {
@@ -52,17 +54,18 @@ export const Default: Story = {
     }
   }
 };
-```
-""" .
+    """
+    ] .
 
 # Story Visibility Standard
 cs:StoryVisibility a cs:CodeStandard ;
     cs:name "storybook/story/visibility" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "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." ;
-    cs:dos """
-(Do) Hide test-only stories that don't represent valid usage.
-```typescript
+    cs:do [
+        cs:description "Hide test-only stories that don't represent valid usage." ;
+        cs:language "typescript" ;
+        cs:code """
 export const FocusedState: Story = {
   args: {
     isOpen: true,
@@ -74,11 +77,12 @@ export const FocusedState: Story = {
     element.focus();
   }
 };
-```
-""" ;
-    cs:donts """
-(Don't) Show implementation details or test states in documentation.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Show implementation details or test states in documentation." ;
+        cs:language "typescript" ;
+        cs:code """
 export const InternalTestState: Story = {
   args: {
     _internalProp: true,  // Bad: Exposing internal state
@@ -90,8 +94,8 @@ export const InternalTestState: Story = {
     }
   }
 };
-```
-""" .
+    """
+    ] .
 
 # Story Format Standard
 cs:StoryFormat a cs:CodeStandard ;
@@ -101,9 +105,10 @@ cs:StoryFormat a cs:CodeStandard ;
 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.""" ;
-    cs:dos """
-(Do) Use the format that matches your specific use case.
-```typescript
+    cs:do [
+        cs:description "Use the format that matches your specific use case." ;
+        cs:language "typescript" ;
+        cs:code """
 // CSF3: For standard component variations through args
 type Story = StoryObj<typeof meta>;
 
@@ -137,11 +142,12 @@ const Template: StoryFn<typeof Component> = (args) => (
 
 export const Primary = Template.bind({});
 Primary.args = { variant: "primary" };
-```
-""" ;
-    cs:donts """
-(Don't) Use a format that doesn't match your use case.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use a format that doesn't match your use case." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Using function format for simple args variation
 export const SimpleButton = () => (
   <Component variant="primary" disabled={false}>
@@ -158,17 +164,18 @@ export const First: Story = {
     </div>
   )]
 };
-```
-""" .
+    """
+    ] .
 
 # Story Decorator Standard
 cs:StoryDecorator a cs:CodeStandard ;
     cs:name "storybook/story/decorator" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "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)." ;
-    cs:dos """
-(Do) Use decorators for static context or layout wrapping.
-```typescript
+    cs:do [
+        cs:description "Use decorators for static context or layout wrapping." ;
+        cs:language "typescript" ;
+        cs:code """
 
 // storybook/decorators.tsx
 
@@ -200,28 +207,30 @@ const meta = {
 } satisfies Meta<typeof Component>;
 
 export default meta;
-```
-""" ;
-    cs:donts """
-(Don't) Use function-based stories for static wrapping that could be done with decorators.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use function-based stories for static wrapping that could be done with decorators." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Using function-based story for static wrapping
 export const WithTheme = (args: ComponentProps) => (
   <ThemeProvider theme="dark">
     <Component {...args} />
   </ThemeProvider>
 );
-```
-""" .
+    """
+    ] .
 
 # Story Import Standard
 cs:StoryImport a cs:CodeStandard ;
     cs:name "storybook/story/import" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "Stories must import their component as 'Component' to maintain a consistent, generic reference that is decoupled from the specific component name." ;
-    cs:dos """
-(Do) Import the component generically as 'Component'.
-```typescript
+    cs:do [
+        cs:description "Import the component generically as 'Component'." ;
+        cs:language "typescript" ;
+        cs:code """
 import Component from "./SkipLink.js";
 
 const meta = {
@@ -234,28 +243,30 @@ export const Default: Story = {
     children: "Skip to main content"
   }
 };
-```
-""" ;
-    cs:donts """
-(Don't) Import the component using its specific name.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Import the component using its specific name." ;
+        cs:language "typescript" ;
+        cs:code """
 import SkipLink from "./SkipLink.js";
 
 const meta = {
   title: "SkipLink",
   component: SkipLink,  // Bad: Using specific component name
 } satisfies Meta<typeof SkipLink>;
-```
-""" .
+    """
+    ] .
 
 # Story Organization Standard
 cs:StoryOrganization a cs:CodeStandard ;
     cs:name "storybook/story/organization" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "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." ;
-    cs:dos """
-(Do) Group related features with clear, descriptive names.
-```typescript
+    cs:do [
+        cs:description "Group related features with clear, descriptive names." ;
+        cs:language "typescript" ;
+        cs:code """
 // Basic usage
 export const Default: Story = {
   args: {
@@ -279,11 +290,12 @@ export const CustomText: Story = {
     children: "Jump to content"
   }
 };
-```
-""" ;
-    cs:donts """
-(Don't) Use unclear names or mix unrelated features in a single story.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use unclear names or mix unrelated features in a single story." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Unclear what this story demonstrates
 export const Variant1: Story = {
   args: {
@@ -294,17 +306,18 @@ export const Variant1: Story = {
     style: { color: "red" }
   }
 };
-```
-""" .
+    """
+    ] .
 
 # Story Testing Standard
 cs:StoryTesting a cs:CodeStandard ;
     cs:name "storybook/story/testing" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "Stories that test component behavior must use the `play` function to simulate user interactions and verify expected outcomes." ;
-    cs:dos """
-(Do) Use play functions to test interactive behavior.
-```typescript
+    cs:do [
+        cs:description "Use play functions to test interactive behavior." ;
+        cs:language "typescript" ;
+        cs:code """
 export const InteractionTest: Story = {
   args: {
     children: "Click Me",
@@ -316,28 +329,30 @@ export const InteractionTest: Story = {
     await expect(args.onClick).toHaveBeenCalled();
   }
 };
-```
-""" ;
-    cs:donts """
-(Don't) Test implementation details or internal state.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Test implementation details or internal state." ;
+        cs:language "typescript" ;
+        cs:code """
 export const InternalTest: Story = {
   play: async ({ component }) => {
     // Bad: Testing internal implementation
     expect(component._internalState).toBe(true);
   }
 };
-```
-""" .
+    """
+    ] .
 
 # Story Documentation Standard
 cs:StoryDocumentation a cs:CodeStandard ;
     cs:name "storybook/story/documentation" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "Story documentation must focus on usage patterns and variations, not implementation details. Each story should demonstrate a specific use case or variation." ;
-    cs:dos """
-(Do) Document usage patterns and variations.
-```typescript
+    cs:do [
+        cs:description "Document usage patterns and variations." ;
+        cs:language "typescript" ;
+        cs:code """
 export const WithCustomTrigger: Story = {
   args: {
     trigger: <button>Custom Trigger</button>
@@ -350,11 +365,12 @@ export const WithCustomTrigger: Story = {
     }
   }
 };
-```
-""" ;
-    cs:donts """
-(Don't) Document implementation details or internal behavior.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Document implementation details or internal behavior." ;
+        cs:language "typescript" ;
+        cs:code """
 export const Default: Story = {
   parameters: {
     docs: {
@@ -364,17 +380,18 @@ export const Default: Story = {
     }
   }
 };
-```
-""" .
+    """
+    ] .
 
 # Story Naming Standard
 cs:StoryNaming a cs:CodeStandard ;
     cs:name "storybook/story/naming" ;
     cs:hasCategory cs:StorybookCategory ;
     cs:description "Story names must be descriptive and follow a consistent pattern. Use PascalCase for story exports and natural language for story titles." ;
-    cs:dos """
-(Do) Use clear, descriptive names that indicate the variation.
-```typescript
+    cs:do [
+        cs:description "Use clear, descriptive names that indicate the variation." ;
+        cs:language "typescript" ;
+        cs:code """
 export const WithCustomStyles: Story = {
   args: {
     className: "custom",
@@ -388,16 +405,17 @@ export const WithCustomStyles: Story = {
     }
   }
 };
-```
-""" ;
-    cs:donts """
-(Don't) Use technical or implementation-focused names.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use technical or implementation-focused names." ;
+        cs:language "typescript" ;
+        cs:code """
 export const TestCase1: Story = {  // Bad: Non-descriptive name
   args: {
     _testFlag: true,  // Bad: Implementation detail
     children: "Content"
   }
 };
-```
-""" .
+    """
+    ] .

package/data/styling.ttl

@@ -18,9 +18,9 @@ cs:TokenTypes a cs:CodeStandard ;
       - Semantic tokens: Map semantic concepts to primitive token values
       - Component tokens: Map component properties to semantic token values
     """ ;
-    cs:dos """
-(Do) Define semantic tokens that map to primitive tokens.
-```
+    cs:do [
+        cs:description "Define semantic tokens that map to primitive tokens." ;
+        cs:code """
 {
   "color": {
     "background": {
@@ -31,11 +31,11 @@ cs:TokenTypes a cs:CodeStandard ;
     }
   }
 }
-```
-""" ;
-    cs:donts """
-(Don't) Skip the semantic layer by mapping component tokens directly to primitives.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Skip the semantic layer by mapping component tokens directly to primitives." ;
+        cs:code """
 {
   "button": {
     "padding": {
@@ -46,17 +46,17 @@ cs:TokenTypes a cs:CodeStandard ;
     }
   }
 }
-```
-""" .
+    """
+    ] .
 
 # Design Token Creation Standard
 cs:DesignTokenCreation a cs:CodeStandard ;
     cs:name "styling/tokens/creation" ;
     cs:hasCategory cs:StylingCategory ;
     cs:description """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.""" ;
-    cs:dos """
-(Do) Create component tokens that reference semantic tokens for design decisions.
-```
+    cs:do [
+        cs:description "Create component tokens that reference semantic tokens for design decisions." ;
+        cs:code """
 {
   "button": {
     "background": {
@@ -65,11 +65,11 @@ cs:DesignTokenCreation a cs:CodeStandard ;
     }
   }
 }
-```
-""" ;
-    cs:donts """
-(Don't) Use raw values for design decisions.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use raw values for design decisions." ;
+        cs:code """
 {
   "button": {
     "background": {
@@ -78,17 +78,17 @@ cs:DesignTokenCreation a cs:CodeStandard ;
     }
   }
 }
-```
-""" .
+    """
+    ] .
 
 # Theme Definition Standard
 cs:ThemeDefinition a cs:CodeStandard ;
     cs:name "styling/themes/definition" ;
     cs:hasCategory cs:StylingCategory ;
     cs:description """Themes are collections of semantic tokens that provide consistent styling across components. See css/themes/activation for implementation details.""" ;
-    cs:dos """
-(Do) Define a theme as a complete set of semantic tokens.
-```
+    cs:do [
+        cs:description "Define a theme as a complete set of semantic tokens." ;
+        cs:code """
 {
   "theme": {
     "canonical": {
@@ -103,11 +103,11 @@ cs:ThemeDefinition a cs:CodeStandard ;
     }
   }
 }
-```
-""" ;
-    cs:donts """
-(Don't) Mix implementation details into theme definitions.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix implementation details into theme definitions." ;
+        cs:code """
 {
   "theme": {
     "canonical": {
@@ -116,8 +116,8 @@ cs:ThemeDefinition a cs:CodeStandard ;
     }
   }
 }
-```
-""" .
+    """
+    ] .
 
 # Token Scoping Standard
 cs:TokenScoping a cs:CodeStandard ;
@@ -128,9 +128,9 @@ cs:TokenScoping a cs:CodeStandard ;
 - Semantic tokens: Theme scope (theme-specific bindings to primitive tokens)
 - Component tokens: Component scope (bindings to semantic tokens)
 """ ;
-    cs:dos """
-(Do) Define primitive tokens in global scope.
-```
+    cs:do [
+        cs:description "Define primitive tokens in global scope." ;
+        cs:code """
 {
   "color": {
     "neutral": {
@@ -141,11 +141,11 @@ cs:TokenScoping a cs:CodeStandard ;
     }
   }
 }
-```
-""" ;
-    cs:donts """
-(Don't) Define primitive tokens in theme scope.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Define primitive tokens in theme scope." ;
+        cs:code """
 {
   "theme": {
     "canonical": {
@@ -160,6 +160,6 @@ cs:TokenScoping a cs:CodeStandard ;
     }
   }
 }
-```
-""" .
+    """
+    ] .