@canonical/code-standards 0.1.0

package/docs/css.md

@@ -0,0 +1,275 @@
+# CSS Standards
+
+Standards for css development.
+
+## css/component/encapsulation
+
+Component styles must be encapsulated using the component's root class as a boundary. All internal element styles must be scoped to the component's namespace.
+
+### Do
+
+(Do) Scope internal element styles using the component's namespace.
+```css
+.ds.button {
+  /* Component root styles */
+  
+  & > .icon {
+    /* Internal element styles */
+    margin-right: var(--button-icon-spacing);
+  }
+}
+```
+
+### Don't
+
+(Don't) Don't style internal elements without the component namespace.
+```css
+/* Bad: Internal element not scoped to component */
+.icon {
+  margin-right: var(--button-icon-spacing);
+}
+```
+
+---
+
+## css/component/states
+
+Component states must be handled using attribute selectors for native states and class modifiers for custom states.
+
+### Do
+
+(Do) Use attribute selectors for native element states.
+```css
+.ds.button {
+  &[disabled] {
+    opacity: var(--button-disabled-opacity);
+  }
+}
+```
+
+### Don't
+
+(Don't) Use class modifiers for native states.
+```css
+/* Bad: Using class for native state */
+.ds.button.disabled {
+  opacity: var(--button-disabled-opacity);
+}
+```
+
+---
+
+## css/properties/values
+
+CSS properties must use design tokens for design decisions (see styling/tokens/creation) and raw values for properties that are independent from design decisions, or "unthemable".
+
+### Do
+
+(Do) Use design tokens for design decisions.
+```css
+.ds.button {
+  /* Design decision uses token */
+  background: var(--button-background);
+}
+```
+(Do) Use raw values for unthemable properties (independent of design decisions).
+```css
+.ds.skip-link {
+    visibility: hidden;
+}
+```
+
+### Don't
+
+(Don't) Use raw values for design decisions.
+```css
+.ds.button {
+  /* Bad: Design decision using raw value */
+  background: #0066CC;
+}
+```
+
+---
+
+## css/selectors/child-elements
+
+Child elements within components must use simple, role-based class names (e.g., `.header`, `.content`, `.icon`) scoped by the parent selector, NOT verbose prefixed names that repeat the component name.
+
+### Do
+
+(Do) Use simple role-based class names scoped by the parent.
+```css
+.ds.accordion-item {
+  & > .header {
+    /* Header styles */
+  }
+
+  & > .header > .chevron {
+    /* Chevron indicator */
+  }
+
+  & > .header > .heading {
+    /* Heading text */
+  }
+
+  & > .content {
+    /* Collapsible content */
+  }
+}
+
+.ds.breadcrumbs-item {
+  & > .link {
+    /* Link styles */
+  }
+
+  & > .separator {
+    /* Separator styles */
+  }
+}
+```
+
+### Don't
+
+(Don't) Use verbose prefixed class names that repeat the component name.
+```css
+/* Bad: Redundant component prefix in child class names */
+.ds.accordion-item .accordion-item-header {
+  /* 'accordion-item-' prefix is redundant */
+}
+
+.ds.accordion-item .accordion-item-chevron {
+  /* Already scoped by parent, no need to repeat */
+}
+
+.ds.timeline-event .timeline-event-marker {
+  /* Verbose and BEM-like */
+}
+```
+
+---
+
+## css/selectors/namespace
+
+All component selectors must be prefixed with the `.ds` namespace (e.g., `.ds.button`).
+
+### Do
+
+(Do) Prefix all component selectors with `.ds`.
+```css
+/* Component root with namespace */
+.ds.button {
+  /* Base styles */
+}
+```
+
+### Don't
+
+(Don't) Omit the `.ds` namespace from component selectors.
+```css
+/* Bad: Missing .ds namespace */
+.button {
+  /* styles */
+}
+```
+
+---
+
+## css/selectors/naming-convention
+
+Component CSS class names must be the kebab-case version of the component's PascalCase name.
+
+### Do
+
+(Do) Convert PascalCase component names to kebab-case for CSS classes:
+- `MyComponent` -> `.ds.my-component`
+- `UserProfile` -> `.ds.user-profile`
+- `Button` -> `.ds.button`
+
+### Don't
+
+(Don't) Use PascalCase or other formats in CSS class names:
+- `.ds.MyComponent` (Bad: Not kebab-case)
+- `.ds.user_profile` (Bad: Not kebab-case)
+
+---
+
+## css/selectors/semantics
+
+CSS class names must describe the purpose or state of an element, not its appearance.
+
+### Do
+
+(Do) Use semantic modifier classes to represent component variations.
+```css
+/* Semantic modifier for a primary button */
+.ds.button.primary {
+  --modifier-color: var(--color-primary);
+}
+```
+
+### Don't
+
+(Don't) Use non-semantic or presentational class names.
+```css
+/* Bad: 'big' describes appearance, not purpose */
+.ds.button.big {
+  padding: 1rem;
+}
+```
+
+---
+
+## css/selectors/specificity
+
+CSS selectors must follow a strict specificity pattern:
+- Component root must use namespace + component name (.ds.button)
+- Single modifier class for variants (.ds.button.primary)
+- Single attribute for states (.ds.button[disabled])
+
+### Do
+
+(Do) Use a single modifier class for component variants.
+```css
+.ds.button.primary {
+  /* Variant: root + modifier (3 classes) */
+  background: var(--button-primary-background);
+}
+```
+
+### Don't
+
+(Don't) Combine multiple modifiers or mix states with variants.
+```css
+/* Bad: Mixing variant with state */
+.ds.button.primary[disabled].large {
+  /* Too specific: root + 2 modifiers + state */
+}
+```
+
+---
+
+## css/themes/activation
+
+Theme tokens must be activated through CSS classes on container elements. See styling/themes/definition for theme token structure.
+
+### Do
+
+(Do) Define semantic tokens within theme classes.
+```css
+.canonical {
+  --spacing-vertical-medium: var(--spacing-unit-2x);
+  --color-background: var(--color-neutral-100);
+}
+```
+
+### Don't
+
+(Don't) Hardcode theme names in component styles.
+```css
+/* Bad: Component locked to specific theme */
+.ds.button {
+  padding: var(--canonical-spacing-vertical-medium);
+}
+```
+
+---

package/docs/icons.md

@@ -0,0 +1,367 @@
+# Icons Standards
+
+Standards for icons development.
+
+## icons/file/naming
+
+Icon files must:
+- Use kebab-case naming
+- Use semantic identifiers
+
+### Do
+
+(Do) Use kebab-case and a semantic identifier for the icon file name.
+```
+warning.svg
+user-profile.svg
+arrow-down.svg
+```
+
+### Don't
+
+(Don't) Include size, theme, or redundant suffixes in the file name.
+```
+warning-16.svg
+warning-dark.svg
+warning_icon.svg
+WARNING.svg
+```
+
+(Don't) Use non-semantic or ambiguous names that do not describe the icon.
+```
+icon1.svg
+shape.svg
+```
+
+---
+
+## icons/file/storage
+
+Each icon shall be stored as a single SVG file in the `icons/` directory.
+
+### Do
+
+(Do) Store each icon as an individual SVG file in the designated `icons/` directory.
+```
+icons/
+  ├── warning.svg
+  ├── search.svg
+  └── github.svg
+```
+
+### Don't
+
+(Don't) Store icons in nested directories or use incorrect file extensions.
+```
+icons/
+  ├── variants/
+  │   └── warning-dark.svg
+  ├── warning/
+  │   └── index.svg
+  └── warning.svg.txt
+```
+
+(Don't) Combine multiple icons into a single SVG file.
+```
+icons/
+  └── all-icons.svg
+```
+
+---
+
+## icons/svg/color-usage
+
+Icon must use `fill` with `currentColor` for their paths and shapes.
+
+### Do
+
+(Do) Use `currentColor` for the `fill` of paths in non-branded icons.
+```svg
+<!-- Non-branded icon -->
+<svg viewBox="0 0 16 16">
+  <g id="search">
+    <path fill="currentColor" d="..." />
+  </g>
+</svg>
+```
+
+### Don't
+
+(Don't) Use hard-coded colors in icons.
+```svg
+<path fill="#000000" d="..." />
+```
+
+(Don't) Use `opacity` to create different shades of a color.
+```svg
+<path fill="currentColor" opacity="0.5" d="..." />
+```
+
+---
+
+## icons/svg/group-element
+
+Each icon's SVG markup must contain a single `<g>` element with an `id` matching the filename (without `.svg`).
+
+### Do
+
+(Do) Include a single `<g>` element with an `id` that matches the filename.
+```svg
+<!-- warning.svg -->
+<svg>
+  <g id="warning">
+    <!-- icon paths -->
+  </g>
+</svg>
+```
+
+### Don't
+
+(Don't) Use multiple `<g>` elements or an `id` that does not match the filename.
+```svg
+<!-- warning.svg -->
+<svg>
+  <g id="icon-group">
+    <!-- icon paths -->
+  </g>
+  <g id="warning-alt">
+    <!-- alternate paths -->
+  </g>
+</svg>
+```
+
+---
+
+## icons/svg/mask-usage
+
+Icons may use SVG masks to negate or partially negate paths, enabling advanced visual effects such as cutouts and overlays.
+
+### Do
+
+(Do) Use SVG <mask> elements to create negative space or overlays in icons.
+Example:
+```svg
+<svg width='16' height='16' xmlns='http://www.w3.org/2000/svg'>
+  <defs>
+    <mask id="error-mask">
+      <rect width="16" height="16" fill="white"/>
+      <path d="..." fill="black"/>
+    </mask>
+  </defs>
+  <g id="error">
+    <circle fill='currentColor' cx='8' cy='8' r='7' mask="url(#error-mask)"/>
+  </g>
+</svg>
+```
+
+(Do) Use <rect> with fill="white" to define the mask area, and <path> with fill="black" to subtract shapes.
+Example:
+```svg
+<mask id="mask">
+  <rect width="16" height="16" fill="white"/>
+  <path d="M4 4h8v8H4z" fill="black"/>
+</mask>
+```
+
+(Do) Use opacity on mask paths to achieve partial negation (e.g., faded or semi-transparent cutouts).
+Example:
+```svg
+<mask id="progress-mask">
+  <rect width="16" height="16" fill="white"/>
+  <path d='...' fill="black" opacity=".5"/>
+</mask>
+```
+
+(Do) Reference the mask in the icon's main shape using mask="url(#mask-id)".
+Example:
+```svg
+<circle fill='currentColor' cx='8' cy='8' r='7' mask="url(#mask-id)"/>
+```
+
+### Don't
+
+(Don't) Use masks without clear purpose or visual benefit.
+Example:
+```svg
+<!-- Bad: Mask used but has no effect -->
+<mask id="empty-mask">
+  <rect width="16" height="16" fill="white"/>
+</mask>
+<circle fill='currentColor' cx='8' cy='8' r='7' mask="url(#empty-mask)"/>
+```
+
+(Don't) use non-semantic mask ids or omit mask references in the main shape.
+Example:
+```svg
+<!-- Bad: Non-semantic mask id -->
+<mask id="123">
+  <rect width="16" height="16" fill="white"/>
+  <path d="..." fill="black"/>
+</mask>
+```
+
+(Don't) rely on masks for simple icons that do not require negative space or overlays.
+Example:
+```svg
+<!-- Bad: Mask used for a simple shape -->
+<mask id="simple-mask">
+  <rect width="16" height="16" fill="white"/>
+</mask>
+<rect fill='currentColor' x='2' y='2' width='12' height='12' mask="url(#simple-mask)"/>
+```
+
+---
+
+## icons/svg/viewbox
+
+All icon SVGs must use a `viewBox` of `0 0 16 16`.
+
+### Do
+
+(Do) Set the `viewBox` attribute to `0 0 16 16` in the `<svg>` element.
+```svg
+<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'>
+  <g id="icon">
+    <!-- Icon content scaled to 16x16 -->
+  </g>
+</svg>
+```
+
+### Don't
+
+(Don't) Use a `viewBox` with dimensions other than `16 16`.
+```svg
+<!-- Bad: Different viewBox size -->
+<svg viewBox="0 0 24 24">
+  <g id="icon">...</g>
+</svg>
+```
+
+(Don't) Use a non-square `viewBox`.
+```svg
+<!-- Bad: Non-square viewBox -->
+<svg viewBox="0 0 16 24">
+  <g id="icon">...</g>
+</svg>
+```
+
+(Don't) Omit the `viewBox` attribute.
+```svg
+<!-- Bad: Missing viewBox -->
+<svg width="16" height="16">
+  <g id="icon">...</g>
+</svg>
+```
+
+---
+
+## icons/type-safety/definition
+
+Icon names must be:
+- Maintained in a type-safe constant array
+- Used to generate the `IconName` type
+- Defined in the icon exporter package
+
+### Do
+
+(Do) Define a constant array of icon names and derive the `IconName` type from it in the icon exporter package.
+```typescript
+// In the icon exporter package
+export const ICON_NAMES = [
+  "warning",
+  "search",
+  "github"
+] as const;
+
+export type IconName = typeof ICON_NAMES[number];
+```
+
+(Do) Import the `IconName` type in consumer code to ensure type safety.
+```typescript
+// In consumer code
+import type { IconName } from '@canonical/ds-assets';
+
+export interface ComponentProps {
+  icon: IconName;
+}
+```
+
+(Do) Use `Pick` to restrict choices from `IconName` when necessary.
+
+```typescript
+// In consumer code
+import type { IconName } from '@canonical/ds-assets';
+
+export interface ComponentProps {
+  icon: Pick<IconName, "warning" | "search">;
+}
+```
+
+### Don't
+
+(Don't) Define icon name types or values on the consumer side.
+```typescript
+// Bad: String literal type defined in consumer code
+type ComponentIconName = "warning" | "search";
+
+export interface ComponentProps {
+    icon: ComponentIconName;
+}
+```
+
+(Don't) Use a generic `string` type for icon names.
+```typescript
+// Bad: No type safety for icon names
+export interface ComponentProps {
+    icon: string;
+}
+```
+
+(Don't) Maintain separate type and value definitions.
+```typescript
+// Bad: Duplication of icon names
+const ICONS = ["warning", "search"];
+type IconName = "warning" | "search";
+```
+
+---
+
+## icons/variant/single-file
+
+Each icon concept must have exactly one SVG file. Size and theme variants are not allowed.
+
+### Do
+
+(Do) Use a single SVG file for each icon and control its size and color with CSS.
+```svg
+<!-- Single icon file -->
+<svg viewBox="0 0 16 16">
+  <g id="warning">
+    <path fill="currentColor" d="..." />
+  </g>
+</svg>
+```
+```css
+/* CSS usage */
+.small-icon { font-size: 1em; } /* 16px */
+.large-icon { font-size: 2em; } /* 32px */
+.warning-icon { color: var(--color-warning); }
+```
+
+### Don't
+
+(Don't) Create multiple files for different icon sizes.
+```
+warning.svg
+warning-small.svg
+warning-large.svg
+```
+
+(Don't) Create multiple files for different themes.
+```
+warning.svg
+warning-dark.svg
+warning-light.svg
+```
+
+---

package/docs/index.md

@@ -0,0 +1,15 @@
+# Code Standards
+
+Standards documentation generated from the code-standards ontology.
+
+## Categories
+
+- [Code](./code.md) (11)
+- [CSS](./css.md) (9)
+- [Icons](./icons.md) (8)
+- [React](./react.md) (14)
+- [Rust](./rust.md) (11)
+- [Storybook](./storybook.md) (9)
+- [Styling](./styling.md) (4)
+- [TSDoc](./tsdoc.md) (3)
+- [Turtle](./turtle.md) (4)