@canonical/code-standards 0.1.0 → 0.1.2

package/data/react.ttl

@@ -15,9 +15,10 @@ cs:ComponentTSDoc a cs:CodeStandard ;
     cs:name "react/component/tsdoc" ;
     cs:hasCategory cs:ReactCategory ;
     cs:description """Component TSDoc documentation must use the description from the design system ontology (DSL). The TSDoc should NOT include @example blocks since stories serve as the examples. The description should be copied verbatim from the DSL, maintaining the original wording and meaning.""" ;
-    cs:dos """
-(Do) Use the description from the DSL ontology verbatim.
-```typescript
+    cs:do [
+        cs:description "Use the description from the DSL ontology verbatim." ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * The label component is a compact, non-interactive visual element used to
  * categorize content or indicate a status. Its primary role is metadata
@@ -31,41 +32,44 @@ const Label = ({ children, criticality, className, ...props }: LabelProps) => (
     {children}
   </span>
 );
-```
-""" ;
-    cs:donts """
-(Don't) Write custom descriptions that deviate from the DSL.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Write custom descriptions that deviate from the DSL." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Custom title and paraphrased description
 /**
  * Label component
  *
  * A compact visual element for status indication.
  */
-```
-
-(Don't) Include @example blocks - stories fulfill this role.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Include @example blocks - stories fulfill this role." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Examples belong in stories, not TSDoc
 /**
  * The label component is a compact...
  *
  * @example
- * ```tsx
  * <Label>Default</Label>
  * <Label criticality="warning">Warning</Label>
- * ```
  */
-```
-
-(Don't) Omit the @implements tag that links to the DSL.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Omit the @implements tag that links to the DSL." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Missing @implements tag
 /**
  * The label component is a compact...
  */
-```
-""" .
+    """
+    ] .
 
 # Component Folder Structure Standard
 cs:ComponentFolderStructure a cs:CodeStandard ;
@@ -73,9 +77,10 @@ cs:ComponentFolderStructure a cs:CodeStandard ;
     cs:extends cs:ComponentFolderStructure ;
     cs:hasCategory cs:ReactCategory ;
     cs:description "Each component must reside in its own folder, which contains all related files: component implementation, tests, type definitions, and optionally stories and styles. Some components may be styleless or may not have stories; in these cases, styles.css and [MyComponent].stories.tsx are optional. Context providers follow a different structure (see react/component/structure/context)." ;
-    cs:dos """
-(Do) Place all component-related files within a single folder named after the component.
-```bash
+    cs:do [
+        cs:description "Place all component-related files within a single folder named after the component." ;
+        cs:language "bash" ;
+        cs:code """
 [MyComponent]/
   ├── [MyComponent].tsx
   ├── [MyComponent].stories.tsx
@@ -83,11 +88,12 @@ cs:ComponentFolderStructure a cs:CodeStandard ;
   ├── index.ts
   ├── styles.css
   └── types.ts
-```
-""" ;
-    cs:donts """
-(Don't) Scatter component files across different parts of the application.
-```bash
+    """
+    ] ;
+    cs:dont [
+        cs:description "Scatter component files across different parts of the application." ;
+        cs:language "bash" ;
+        cs:code """
 # Bad: Files are not co-located
 components/
   ├── [MyComponent].tsx
@@ -95,46 +101,50 @@ stories/
   └── [MyComponent].stories.tsx
 styles/
   └── [MyComponent].css
-```
-""" .
+    """
+    ] .
 
 # Barrel Exports Standard
 cs:BarrelExports a cs:CodeStandard ;
     cs:name "react/component/barrel-exports" ;
     cs:hasCategory cs:ReactCategory ;
     cs:description "The index.ts file must be a complete barrel export for the component folder, re-exporting all public APIs." ;
-    cs:dos """
-(Do) Create an index.ts file that re-exports all public APIs from the component folder.
-```typescript
+    cs:do [
+        cs:description "Create an index.ts file that re-exports all public APIs from the component folder." ;
+        cs:language "typescript" ;
+        cs:code """
 // index.ts
 export { default as [MyComponent] } from './[MyComponent].js';
 export type * from './types.js';
 // If you have multiple components:
 export { default as SubComponent } from './SubComponent.js';
-```
-""" ;
-    cs:donts """
-(Don't) Omit the index.ts file or fail to re-export all public APIs.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Omit the index.ts file or fail to re-export all public APIs." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: index.ts only exports default, omits types and named exports
 export { default } from './[MyComponent].js';
-```
-
-(Don't) Use `export * from './types.js'` as it allows value exports, which is not expected for types files.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use `export * from './types.js'` as it allows value exports, which is not expected for types files." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Using export * from './types.js' allows value exports, which is not allowed
 export * from './types.js';
-```
-""" .
+    """
+    ] .
 
 # Component File Naming Standard
 cs:ComponentFileNaming a cs:CodeStandard ;
     cs:name "react/component/file-naming" ;
     cs:hasCategory cs:ReactCategory ;
     cs:description "Component folder and file naming is based on scope. Component-specific files (implementation, stories, tests) must be prefixed with the component's name (e.g., `MyComponent.tsx`, `MyComponent.stories.tsx`). Domain-level files that serve the entire folder (e.g., `Context.tsx`, `styles.css`, `types.ts`) should use generic, descriptive names, as the folder already provides the domain context." ;
-    cs:dos """
-(Do) Prefix component-specific files and use generic names for domain-level files.
-```
+    cs:do [
+        cs:description "Prefix component-specific files and use generic names for domain-level files." ;
+        cs:code """
 [MyComponent]/
   ├── [MyComponent].tsx           # Component-specific
   ├── [MyComponent].stories.tsx   # Component-specific
@@ -142,17 +152,17 @@ cs:ComponentFileNaming a cs:CodeStandard ;
   ├── Context.tsx               # Domain-level
   ├── types.ts                  # Domain-level
   └── styles.css                # Domain-level
-```
-""" ;
-    cs:donts """
-(Don't) Add redundant prefixes to domain-level files.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Add redundant prefixes to domain-level files." ;
+        cs:code """
 [MyComponent]/
   ├── [MyComponent].Context.tsx   # Bad: Redundant prefix
   ├── [MyComponent].types.ts      # Bad: Redundant prefix
   └── [MyComponent].styles.css    # Bad: Redundant prefix
-```
-""" .
+    """
+    ] .
 
 # Component Props Standard
 cs:ComponentProps a cs:CodeStandard ;
@@ -163,9 +173,10 @@ cs:ComponentProps a cs:CodeStandard ;
 - Be destructured when used in markup
 - Be spread to the root element when unused
 - Follow type-specific patterns based on what the component renders""" ;
-    cs:dos """
-(Do) Document props with TSDoc comments and use proper destructuring and spreading.
-```typescript
+    cs:do [
+        cs:description "Document props with TSDoc comments and use proper destructuring and spreading." ;
+        cs:language "typescript" ;
+        cs:code """
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** The button's text content */
   label: string;
@@ -190,11 +201,12 @@ const Button = ({
     <span>{label}</span>
   </button>
 );
-```
-""" ;
-    cs:donts """
-(Don't) Mix explicit and spread props or destructure props unnecessarily.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix explicit and spread props or destructure props unnecessarily." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Mixing explicit props with spread
 const Button = (props: ButtonProps) => (
   <button
@@ -225,8 +237,8 @@ const Button = ({
     {label}
   </button>
 );
-```
-""" .
+    """
+    ] .
 
 # HTML Rendering Components Props Standard
 cs:HTMLRenderingProps a cs:CodeStandard ;
@@ -234,66 +246,70 @@ cs:HTMLRenderingProps a cs:CodeStandard ;
     cs:hasCategory cs:ReactCategory ;
     cs:extends cs:ComponentProps ;
     cs:description "Components that render HTML markup must extend the base HTML element props interface to enable passing native properties through spreading." ;
-    cs:dos """
-(Do) Extend the appropriate React HTML props interface and add component-specific props.
-```typescript
+    cs:do [
+        cs:description "Extend the appropriate React HTML props interface and add component-specific props." ;
+        cs:language "typescript" ;
+        cs:code """
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** The button label */
   label: string;
 }
-```
-""" ;
-    cs:donts """
-(Don't) Manually redefine standard HTML attributes that are already available through the base interface.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Manually redefine standard HTML attributes that are already available through the base interface." ;
+        cs:language "typescript" ;
+        cs:code """
 export interface ButtonProps {
   /** The button label */
   label: string;
   onClick?: () => void;    // Bad: Duplicates HTML button props
   disabled?: boolean;      // Bad: Duplicates HTML button props
 }
-```
-""" .
+    """
+    ] .
 
 # Component Naming Standard
 cs:ComponentNaming a cs:CodeStandard ;
     cs:name "react/component/naming" ;
     cs:hasCategory cs:ReactCategory ;
     cs:description "Components must use PascalCase naming and be descriptive of their purpose." ;
-    cs:dos """
-(Do) Use PascalCase and descriptive names for components:
+    cs:do [
+        cs:description """Use PascalCase and descriptive names for components:
 UserProfile
 NavigationBar
-SearchResultList
-""" ;
-    cs:donts """
-(Don't) Use non-PascalCase or unclear names:
+SearchResultList"""
+    ] ;
+    cs:dont [
+        cs:description """Use non-PascalCase or unclear names:
 userProfile
 navigation_bar
-searchresultlist
-""" .
+searchresultlist"""
+    ] .
 
 # Hook Naming Standard
 cs:HookNaming a cs:CodeStandard ;
     cs:name "react/hooks/naming" ;
     cs:hasCategory cs:ReactCategory ;
     cs:description "The hook name must start with 'use' and clearly describe its purpose." ;
-    cs:dos """
-(Do) Name custom hooks so the hook name starts with 'use' and is descriptive:
-```typescript
+    cs:do [
+        cs:description "Name custom hooks so the hook name starts with 'use' and is descriptive" ;
+        cs:language "typescript" ;
+        cs:code """
 useWindowSize()
 useAuthentication()
 useFormValidation()
-```
-""" ;
-    cs:donts """
-(Don't) Name hooks without the 'use' prefix at the start of the hook name:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Name hooks without the 'use' prefix at the start of the hook name" ;
+        cs:language "typescript" ;
+        cs:code """
 windowSize()
 getAuth()
 formValidation()
-```
-""" .
+    """
+    ] .
 
 # Component Dependencies Standard
 cs:ComponentDependencies a cs:CodeStandard ;
@@ -303,9 +319,9 @@ cs:ComponentDependencies a cs:CodeStandard ;
 - Subcomponents must be in a `common/` folder within the parent component's directory
 - Dependencies can flow downwards (parent to subcomponent) or sideways (between siblings)
 - Dependencies must not flow upwards (subcomponent to parent)""" ;
-    cs:dos """
-(Do) Place subcomponents in a `common/` folder inside the parent component directory.
-```
+    cs:do [
+        cs:description "Place subcomponents in a `common/` folder inside the parent component directory." ;
+        cs:code """
 Card/
   ├── Card.tsx
   ├── common/
@@ -316,30 +332,35 @@ Card/
   │   └── utils/
   │       └── helpers.ts
   └── index.ts
-```
-
-(Do) Allow subcomponents to depend on siblings or shared utilities within the same component scope.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Allow subcomponents to depend on siblings or shared utilities within the same component scope." ;
+        cs:language "typescript" ;
+        cs:code """
 // Header.tsx can import from utils/
 import { helper } from '../utils/helpers.js';
 
 // Footer.tsx can import from Header.tsx
 import Header from '../Header.js';
-```
-""" ;
-    cs:donts """
-(Don't) Create dependencies that flow upwards from a subcomponent to its parent.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create dependencies that flow upwards from a subcomponent to its parent." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Header.tsx in Card/common/ should not import from Card.tsx
 import Card from '../../Card.js';
-```
-
-(Don't) Allow external components to depend on the internal structure of another component.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Allow external components to depend on the internal structure of another component." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: AnotherComponent should not import from Card's internal common folder
 import Header from '../Card/common/Header.js';
-```
-""" .
+    """
+    ] .
 
 # Subcomponents Export and Consumption API Standard
 cs:SubcomponentsExportAPI a cs:CodeStandard ;
@@ -355,65 +376,77 @@ Public subcomponents must be:
 - Kept to a single level of nesting.
 
 Private subcomponents must remain internal to the component's implementation and not be exported by any file.""" ;
-    cs:dos """
-(Do) Export public subcomponents by attaching them to the parent component using dot notation:
-```typescript
+    cs:do [
+        cs:description "Export public subcomponents by attaching them to the parent component using dot notation" ;
+        cs:language "typescript" ;
+        cs:code """
 const Item = (props: ItemProps) => { /* ... */ };
 const Accordion = (props: AccordionProps) => { /* ... */ };
 Accordion.Item = Item;
 export default Accordion;
-```
-
-(Do) Use semantic, self-descriptive names for subcomponents:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Use semantic, self-descriptive names for subcomponents" ;
+        cs:language "typescript" ;
+        cs:code """
 Accordion.Item
 Card.Header
 Card.Footer
-```
-
-(Do) Keep subcomponent nesting to a single level:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Keep subcomponent nesting to a single level" ;
+        cs:language "typescript" ;
+        cs:code """
 <Card>
   <Card.Header />
   <Card.Footer />
 </Card>
-```
-
-""" ;
-    cs:donts """
-(Don't) Repeat the parent component name in subcomponent names:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Repeat the parent component name in subcomponent names" ;
+        cs:language "typescript" ;
+        cs:code """
 Card.CardHeader = Header; // Bad: Redundant 'Card' prefix
-```
-
-(Don't) Map a subcomponent to a different name (renaming):
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Map a subcomponent to a different name (renaming)" ;
+        cs:language "typescript" ;
+        cs:code """
 Card.Top = Header; // Bad: Mapping 'Header' to 'Top' is not allowed
-```
-
-(Don't) Use non-semantic or unclear subcomponent names:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use non-semantic or unclear subcomponent names" ;
+        cs:code """
 Card/
   └── common/
       ├── Part/           # Bad: Too vague, not semantic - what part?
       ├── Element/        # Bad: Too vague, not semantic - what element?
-```
-
-(Don't) Nest subcomponents more than one level deep:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Nest subcomponents more than one level deep" ;
+        cs:language "typescript" ;
+        cs:code """
 <Card>
   <Card.Header>
     <Card.Header.Title />
   </Card.Header>
 </Card>
-```
-
-(Don't) Export private subcomponents that are not intended for public use.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Export private subcomponents that are not intended for public use." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Exporting internal-only subcomponents
 export { InternalHelper };
-```
-""" .
+    """
+    ] .
 
 # CSS ClassName Construction Standard
 cs:ClassNameConstruction a cs:CodeStandard ;
@@ -428,9 +461,10 @@ cs:ClassNameConstruction a cs:CodeStandard ;
     b. Modifier Classes: Classes derived from component props (e.g., `emphasis`, `severity`).
     c. Consumer Classes: The `className` prop passed by the consumer.
 4.  Filtering and Joining: The array must be processed with `.filter(Boolean).join(" ")` to remove any falsy values (e.g., undefined props, expressions that evaluate to false) and create the final space-delimited string.""" ;
-    cs:dos """
-(Do) Follow the complete pattern for class name construction.
-```tsx
+    cs:do [
+        cs:description "Follow the complete pattern for class name construction." ;
+        cs:language "tsx" ;
+        cs:code """
 const componentCssClassName = "ds badge";
 
 const Badge = ({
@@ -450,27 +484,32 @@ const Badge = ({
     </span>
   );
 };
-```
-""" ;
-    cs:donts """
-(Don't) Hardcode the base class name inside the JSX.
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Hardcode the base class name inside the JSX." ;
+        cs:language "tsx" ;
+        cs:code """
 // Bad: Base class "ds badge" is hardcoded.
 <span className={["ds badge", severity, className].filter(Boolean).join(" ")}>
-```
-
-(Don't) Place the consumer `className` prop before other classes.
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Place the consumer `className` prop before other classes." ;
+        cs:language "tsx" ;
+        cs:code """
 // Bad: Consumer class is first
 <span className={[className, componentCssClassName, severity].filter(Boolean).join(" ")}>
-```
-
-(Don't) Use string concatenation or template literals to add class names.
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use string concatenation or template literals to add class names." ;
+        cs:language "tsx" ;
+        cs:code """
 // Bad: Harder to read and maintain, vulnerable to inconsistent formatting
 <span className={`${componentCssClassName} ${severity} ${className}`}>
-```
-""" .
+    """
+    ] .
 
 # Wrapper Component Props Standard
 cs:WrapperComponentProps a cs:CodeStandard ;
@@ -478,9 +517,10 @@ cs:WrapperComponentProps a cs:CodeStandard ;
     cs:hasCategory cs:ReactCategory ;
     cs:extends cs:ComponentProps ;
     cs:description "Wrapper components must use namespaced props for inner components and accept unscoped props for the wrapper element." ;
-    cs:dos """
-(Do) Use namespaced props for inner components and unscoped props for the wrapper element.
-```tsx
+    cs:do [
+        cs:description "Use namespaced props for inner components and unscoped props for the wrapper element." ;
+        cs:language "tsx" ;
+        cs:code """
 interface ThumbnailSectionProps extends SectionProps {
   /** Props for the thumbnail image */
   imageProps: Omit<React.ImgHTMLAttributes<HTMLImageElement>, "alt"> & {
@@ -497,11 +537,12 @@ const ThumbnailSection = ({
     <img {...imageProps} />
   </Section>
 );
-```
-""" ;
-    cs:donts """
-(Don't) Mix prop scopes between wrapper and inner components.
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix prop scopes between wrapper and inner components." ;
+        cs:language "tsx" ;
+        cs:code """
 interface ThumbnailSectionProps {
   src: string;      // Bad: Unscoped image props
   alt: string;      // Bad: Unscoped image props
@@ -513,8 +554,8 @@ const ThumbnailSection = ({ src, alt, width, ...props }: ThumbnailSectionProps)
     <img src={src} alt={alt} width={width} />
   </Section>
 );
-```
-""" .
+    """
+    ] .
 
 # Custom Hooks Standard
 cs:CustomHooks a cs:CodeStandard ;
@@ -528,17 +569,21 @@ cs:CustomHooks a cs:CodeStandard ;
 
 All of the types for a domain level's hooks must be defined in the `hooks/types.ts` file of that folder.
 Each hook must define a [HookName]Props and [HookName]Result type in `hooks/types.ts`.""" ;
-    cs:dos """
-(Do) Create a custom hook that focuses on a single concern within the domain.
-```typescript
+    cs:do [
+        cs:description "Create a custom hook that focuses on a single concern within the domain." ;
+        cs:language "typescript" ;
+        cs:code """
 // [MyComponent]/hooks/useWindowFitment.ts
 const useWindowFitment = ({
   onBestPositionChange,
   autoFit = false,
 }: UseWindowFitmentProps): UseWindowFitmentResult => {
-```
-(Do) Create hook types in `hooks/types.ts`.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Create hook types in `hooks/types.ts`." ;
+        cs:language "typescript" ;
+        cs:code """
 // [MyComponent]/hooks/types.ts
 export interface UseWindowFitmentProps {
   /**
@@ -571,21 +616,23 @@ export interface UseWindowFitmentResult {
    */
   popupPositionStyle: CSSProperties;
 }
-```
-
-""" ;
-    cs:donts """
-(Don't) Create a custom hook for simple, non-reusable state.
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create a custom hook for simple, non-reusable state." ;
+        cs:language "tsx" ;
+        cs:code """
 // Bad: Unnecessary abstraction for a simple counter
 const useCounter = () => {
   const [count, setCount] = useState(0);
   return { count, setCount };
 };
-```
-
-(Don't) Mix multiple concerns in a single hook
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix multiple concerns in a single hook" ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Multiple concerns in one hook
 const useUserData = () => {
   const [isAuthenticated, setIsAuthenticated] = useState(false);
@@ -594,8 +641,8 @@ const useUserData = () => {
   const [notifications, setNotifications] = useState([]);
   return { isAuthenticated, profile, settings, notifications };
 };
-```
-""" .
+    """
+    ] .
 
 # Context Provider Structure Standard
 cs:ContextProviderStructure a cs:CodeStandard ;
@@ -603,9 +650,9 @@ cs:ContextProviderStructure a cs:CodeStandard ;
     cs:extends cs:ComponentFolderStructure ;
     cs:hasCategory cs:ReactCategory ;
     cs:description "Context providers must use `Provider.tsx` as the main component file instead of the standard component naming pattern `[MyComponent].tsx`. Provider prop and return types must be defined in the hook-level types file `hooks/types.ts` with `UseProviderStateProps` (containing all `ProviderProps` minus `children`) and `UseProviderStateResult` (matching the context options)." ;
-    cs:dos """
-(Do) Organize provider-related files by separating concerns into distinct files: place the context definition in `Context.tsx`, the provider implementation in `Provider.tsx`, and provider-specific hooks in a `hooks/` directory. Create a `hooks/useProviderState.ts` file to centrally manage the state of the provider.`
-```
+    cs:do [
+        cs:description "Organize provider-related files by separating concerns into distinct files: place the context definition in `Context.tsx`, the provider implementation in `Provider.tsx`, and provider-specific hooks in a `hooks/` directory. Create a `hooks/useProviderState.ts` file to centrally manage the state of the provider.`" ;
+        cs:code """
 [MyComponent]/
   ├── Context.tsx
   ├── Provider.tsx
@@ -620,10 +667,12 @@ cs:ContextProviderStructure a cs:CodeStandard ;
       ├── index.ts
       ├── types.ts
       └── useProviderState.ts
-```
-(Do) Create the context type within `types.ts`.
-
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Create the context type within `types.ts`." ;
+        cs:language "typescript" ;
+        cs:code """
 // [MyComponent]/types.ts
 /** The value of the config context */
 export interface ContextOptions {
@@ -632,11 +681,12 @@ export interface ContextOptions {
   /** Toggles the baseline grid's visibility. */
   toggleShowBaselineGrid: () => void;
 }
-```
-
-(Do) create the provider props type within `types.ts`, accepting `children` at a minimum and more props as needed.
-
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "create the provider props type within `types.ts`, accepting `children` at a minimum and more props as needed." ;
+        cs:language "typescript" ;
+        cs:code """
 // [MyComponent]/types.ts
 
 export interface ProviderProps {
@@ -644,10 +694,12 @@ export interface ProviderProps {
     children: React.ReactNode;
     // ...other props...
 }
-```
-
-(Do) Create a `Context.tsx` file for the context definition.
-```tsx
+    """
+    ] ;
+    cs:do [
+        cs:description "Create a `Context.tsx` file for the context definition." ;
+        cs:language "tsx" ;
+        cs:code """
 // [MyComponent]/Context.tsx
 import { createContext } from "react";
 import type { ContextOptions } from "./types.js";
@@ -655,11 +707,12 @@ import type { ContextOptions } from "./types.js";
 const Context = createContext<ContextOptions | undefined>(undefined);
 
 export default Context;
-```
-
-
-(Do) Use `Provider.tsx` as the main component file. The provider is responsible for wrapping children with the context.
-```tsx
+    """
+    ] ;
+    cs:do [
+        cs:description "Use `Provider.tsx` as the main component file. The provider is responsible for wrapping children with the context." ;
+        cs:language "tsx" ;
+        cs:code """
 // [MyComponent]/Provider.tsx
 import Context from "./Context.js";
 import { useProviderState } from "./hooks/useProviderState.js";
@@ -671,10 +724,12 @@ const Provider = ({ children }: ProviderProps) => {
 };
 
 export default Provider;
-```
-
-(Do) Use `index.ts` to export the `Provider` as a named component that matches the folder name, casting it to the component type.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Use `index.ts` to export the `Provider` as a named component that matches the folder name, casting it to the component type." ;
+        cs:language "typescript" ;
+        cs:code """
 // [MyComponent]/types.ts
 import type { ReactElement } from "react";
 
@@ -688,10 +743,12 @@ import type { [MyComponent] } from "./types.js";
 
 export const [MyComponent] = Provider as [MyComponent]Component;
 export default [MyComponent];
-```
-
-(Do) Create provider state hook types in `hooks/types.ts` for context providers.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Create provider state hook types in `hooks/types.ts` for context providers." ;
+        cs:language "typescript" ;
+        cs:code """
 // [MyComponent]/hooks/types.ts
 import type { ContextOptions, ProviderProps } from "../types.js";
 
@@ -700,10 +757,12 @@ export type UseProviderStateProps = Omit<ProviderProps, "children">;
 
 // The result of the provider state hook. This should match the context options defined in the main component types file.
 export type UseProviderStateResult = ContextOptions;
-```
-
-(Do) Create a provider state hook implementation.
-```tsx
+    """
+    ] ;
+    cs:do [
+        cs:description "Create a provider state hook implementation." ;
+        cs:language "tsx" ;
+        cs:code """
 // [MyComponent]/hooks/useProviderState.ts
 import { useContext } from "react";
 import type { UseProviderStateProps, UseProviderStateResult } from "./types.js";
@@ -716,37 +775,40 @@ const useProviderState = ({
 }: UseProviderStateProps): UseProviderStateResult => {
  // centralize the entire provider state here...
 }
-```
-""" ;
-    cs:donts """
-(Don't) Create a separate component file (e.g., `[MyComponent].tsx`) when `Provider.tsx` exists. The provider is the main component.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create a separate component file (e.g., `[MyComponent].tsx`) when `Provider.tsx` exists. The provider is the main component." ;
+        cs:code """
 [MyComponent]/
   ├── [MyComponent].tsx
   └── Provider.tsx
-```
-
-(Don't) Nest context-related files in a `context/` subfolder.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Nest context-related files in a `context/` subfolder." ;
+        cs:code """
 [MyComponent]/
   └── context/ # Unnecessary nesting
       ├── Context.tsx
       └── Provider.tsx
-```
-
-(Don't) Create multiple provider files within the same component folder.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create multiple provider files within the same component folder." ;
+        cs:code """
 [MyComponent]/
   ├── Provider.tsx
   └── AnotherProvider.tsx # Only one provider per component
-```
-
-(Don't) Mix concerns of the Provider and its state.
-
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix concerns of the Provider and its state." ;
+        cs:language "tsx" ;
+        cs:code """
 exort const Provider = ({ children }: ProviderProps) => {
   const [state, setState] = useState(...); // Bad: State logic mixed in
   return <Context.Provider value={{ state, setState }}>{children}</Context.Provider>;
 };
-```
-""" .
+    """
+    ] .