@canonical/code-standards 0.1.0 → 0.1.2

package/docs/css.md

@@ -8,7 +8,7 @@ Component styles must be encapsulated using the component's root class as a boun
 
 ### Do
 
-(Do) Scope internal element styles using the component's namespace.
+Scope internal element styles using the component's namespace.
 ```css
 .ds.button {
   /* Component root styles */
@@ -22,7 +22,7 @@ Component styles must be encapsulated using the component's root class as a boun
 
 ### Don't
 
-(Don't) Don't style internal elements without the component namespace.
+Don't style internal elements without the component namespace.
 ```css
 /* Bad: Internal element not scoped to component */
 .icon {
@@ -38,7 +38,7 @@ Component states must be handled using attribute selectors for native states and
 
 ### Do
 
-(Do) Use attribute selectors for native element states.
+Use attribute selectors for native element states.
 ```css
 .ds.button {
   &[disabled] {
@@ -49,7 +49,7 @@ Component states must be handled using attribute selectors for native states and
 
 ### Don't
 
-(Don't) Use class modifiers for native states.
+Use class modifiers for native states.
 ```css
 /* Bad: Using class for native state */
 .ds.button.disabled {
@@ -65,14 +65,15 @@ CSS properties must use design tokens for design decisions (see styling/tokens/c
 
 ### Do
 
-(Do) Use design tokens for design decisions.
+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).
+
+Use raw values for unthemable properties (independent of design decisions).
 ```css
 .ds.skip-link {
     visibility: hidden;
@@ -81,7 +82,7 @@ CSS properties must use design tokens for design decisions (see styling/tokens/c
 
 ### Don't
 
-(Don't) Use raw values for design decisions.
+Use raw values for design decisions.
 ```css
 .ds.button {
   /* Bad: Design decision using raw value */
@@ -97,7 +98,7 @@ Child elements within components must use simple, role-based class names (e.g.,
 
 ### Do
 
-(Do) Use simple role-based class names scoped by the parent.
+Use simple role-based class names scoped by the parent.
 ```css
 .ds.accordion-item {
   & > .header {
@@ -130,7 +131,7 @@ Child elements within components must use simple, role-based class names (e.g.,
 
 ### Don't
 
-(Don't) Use verbose prefixed class names that repeat the component name.
+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 {
@@ -154,7 +155,7 @@ All component selectors must be prefixed with the `.ds` namespace (e.g., `.ds.bu
 
 ### Do
 
-(Do) Prefix all component selectors with `.ds`.
+Prefix all component selectors with `.ds`.
 ```css
 /* Component root with namespace */
 .ds.button {
@@ -164,7 +165,7 @@ All component selectors must be prefixed with the `.ds` namespace (e.g., `.ds.bu
 
 ### Don't
 
-(Don't) Omit the `.ds` namespace from component selectors.
+Omit the `.ds` namespace from component selectors.
 ```css
 /* Bad: Missing .ds namespace */
 .button {
@@ -176,18 +177,21 @@ All component selectors must be prefixed with the `.ds` namespace (e.g., `.ds.bu
 
 ## css/selectors/naming-convention
 
-Component CSS class names must be the kebab-case version of the component's PascalCase name.
+Convert PascalCase component names to kebab-case for CSS classes:
+- `MyComponent` -> `.ds.my-component`
+- `UserProfile` -> `.ds.user-profile`
+- `Button` -> `.ds.button`
 
 ### Do
 
-(Do) Convert PascalCase component names to kebab-case for CSS classes:
+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:
+Use PascalCase or other formats in CSS class names:
 - `.ds.MyComponent` (Bad: Not kebab-case)
 - `.ds.user_profile` (Bad: Not kebab-case)
 
@@ -199,7 +203,7 @@ CSS class names must describe the purpose or state of an element, not its appear
 
 ### Do
 
-(Do) Use semantic modifier classes to represent component variations.
+Use semantic modifier classes to represent component variations.
 ```css
 /* Semantic modifier for a primary button */
 .ds.button.primary {
@@ -209,7 +213,7 @@ CSS class names must describe the purpose or state of an element, not its appear
 
 ### Don't
 
-(Don't) Use non-semantic or presentational class names.
+Use non-semantic or presentational class names.
 ```css
 /* Bad: 'big' describes appearance, not purpose */
 .ds.button.big {
@@ -228,7 +232,7 @@ CSS selectors must follow a strict specificity pattern:
 
 ### Do
 
-(Do) Use a single modifier class for component variants.
+Use a single modifier class for component variants.
 ```css
 .ds.button.primary {
   /* Variant: root + modifier (3 classes) */
@@ -238,7 +242,7 @@ CSS selectors must follow a strict specificity pattern:
 
 ### Don't
 
-(Don't) Combine multiple modifiers or mix states with variants.
+Combine multiple modifiers or mix states with variants.
 ```css
 /* Bad: Mixing variant with state */
 .ds.button.primary[disabled].large {
@@ -254,7 +258,7 @@ Theme tokens must be activated through CSS classes on container elements. See st
 
 ### Do
 
-(Do) Define semantic tokens within theme classes.
+Define semantic tokens within theme classes.
 ```css
 .canonical {
   --spacing-vertical-medium: var(--spacing-unit-2x);
@@ -264,7 +268,7 @@ Theme tokens must be activated through CSS classes on container elements. See st
 
 ### Don't
 
-(Don't) Hardcode theme names in component styles.
+Hardcode theme names in component styles.
 ```css
 /* Bad: Component locked to specific theme */
 .ds.button {

package/docs/icons.md

@@ -10,7 +10,7 @@ Icon files must:
 
 ### Do
 
-(Do) Use kebab-case and a semantic identifier for the icon file name.
+Use kebab-case and a semantic identifier for the icon file name.
 ```
 warning.svg
 user-profile.svg
@@ -19,7 +19,7 @@ arrow-down.svg
 
 ### Don't
 
-(Don't) Include size, theme, or redundant suffixes in the file name.
+Include size, theme, or redundant suffixes in the file name.
 ```
 warning-16.svg
 warning-dark.svg
@@ -27,7 +27,7 @@ warning_icon.svg
 WARNING.svg
 ```
 
-(Don't) Use non-semantic or ambiguous names that do not describe the icon.
+Use non-semantic or ambiguous names that do not describe the icon.
 ```
 icon1.svg
 shape.svg
@@ -41,7 +41,7 @@ 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.
+Store each icon as an individual SVG file in the designated `icons/` directory.
 ```
 icons/
   ├── warning.svg
@@ -51,7 +51,7 @@ icons/
 
 ### Don't
 
-(Don't) Store icons in nested directories or use incorrect file extensions.
+Store icons in nested directories or use incorrect file extensions.
 ```
 icons/
   ├── variants/
@@ -61,7 +61,7 @@ icons/
   └── warning.svg.txt
 ```
 
-(Don't) Combine multiple icons into a single SVG file.
+Combine multiple icons into a single SVG file.
 ```
 icons/
   └── all-icons.svg
@@ -75,7 +75,7 @@ Icon must use `fill` with `currentColor` for their paths and shapes.
 
 ### Do
 
-(Do) Use `currentColor` for the `fill` of paths in non-branded icons.
+Use `currentColor` for the `fill` of paths in non-branded icons.
 ```svg
 <!-- Non-branded icon -->
 <svg viewBox="0 0 16 16">
@@ -87,12 +87,12 @@ Icon must use `fill` with `currentColor` for their paths and shapes.
 
 ### Don't
 
-(Don't) Use hard-coded colors in icons.
+Use hard-coded colors in icons.
 ```svg
 <path fill="#000000" d="..." />
 ```
 
-(Don't) Use `opacity` to create different shades of a color.
+Use `opacity` to create different shades of a color.
 ```svg
 <path fill="currentColor" opacity="0.5" d="..." />
 ```
@@ -105,7 +105,7 @@ Each icon's SVG markup must contain a single `<g>` element with an `id` matching
 
 ### Do
 
-(Do) Include a single `<g>` element with an `id` that matches the filename.
+Include a single `<g>` element with an `id` that matches the filename.
 ```svg
 <!-- warning.svg -->
 <svg>
@@ -117,7 +117,7 @@ Each icon's SVG markup must contain a single `<g>` element with an `id` matching
 
 ### Don't
 
-(Don't) Use multiple `<g>` elements or an `id` that does not match the filename.
+Use multiple `<g>` elements or an `id` that does not match the filename.
 ```svg
 <!-- warning.svg -->
 <svg>
@@ -134,12 +134,13 @@ Each icon's SVG markup must contain a single `<g>` element with an `id` matching
 
 ## icons/svg/mask-usage
 
-Icons may use SVG masks to negate or partially negate paths, enabling advanced visual effects such as cutouts and overlays.
+Use SVG <mask> elements to create negative space or overlays in icons.
+Example
 
 ### Do
 
-(Do) Use SVG <mask> elements to create negative space or overlays in icons.
-Example:
+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>
@@ -154,8 +155,8 @@ Example:
 </svg>
 ```
 
-(Do) Use <rect> with fill="white" to define the mask area, and <path> with fill="black" to subtract shapes.
-Example:
+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"/>
@@ -163,8 +164,8 @@ Example:
 </mask>
 ```
 
-(Do) Use opacity on mask paths to achieve partial negation (e.g., faded or semi-transparent cutouts).
-Example:
+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"/>
@@ -172,16 +173,16 @@ Example:
 </mask>
 ```
 
-(Do) Reference the mask in the icon's main shape using mask="url(#mask-id)".
-Example:
+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:
+Use masks without clear purpose or visual benefit.
+Example
 ```svg
 <!-- Bad: Mask used but has no effect -->
 <mask id="empty-mask">
@@ -190,8 +191,8 @@ Example:
 <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:
+use non-semantic mask ids or omit mask references in the main shape.
+Example
 ```svg
 <!-- Bad: Non-semantic mask id -->
 <mask id="123">
@@ -200,8 +201,8 @@ Example:
 </mask>
 ```
 
-(Don't) rely on masks for simple icons that do not require negative space or overlays.
-Example:
+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">
@@ -218,7 +219,7 @@ 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.
+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">
@@ -229,7 +230,7 @@ All icon SVGs must use a `viewBox` of `0 0 16 16`.
 
 ### Don't
 
-(Don't) Use a `viewBox` with dimensions other than `16 16`.
+Use a `viewBox` with dimensions other than `16 16`.
 ```svg
 <!-- Bad: Different viewBox size -->
 <svg viewBox="0 0 24 24">
@@ -237,7 +238,7 @@ All icon SVGs must use a `viewBox` of `0 0 16 16`.
 </svg>
 ```
 
-(Don't) Use a non-square `viewBox`.
+Use a non-square `viewBox`.
 ```svg
 <!-- Bad: Non-square viewBox -->
 <svg viewBox="0 0 16 24">
@@ -245,7 +246,7 @@ All icon SVGs must use a `viewBox` of `0 0 16 16`.
 </svg>
 ```
 
-(Don't) Omit the `viewBox` attribute.
+Omit the `viewBox` attribute.
 ```svg
 <!-- Bad: Missing viewBox -->
 <svg width="16" height="16">
@@ -264,7 +265,7 @@ Icon names must be:
 
 ### Do
 
-(Do) Define a constant array of icon names and derive the `IconName` type from it in the icon exporter package.
+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 = [
@@ -276,7 +277,7 @@ export const ICON_NAMES = [
 export type IconName = typeof ICON_NAMES[number];
 ```
 
-(Do) Import the `IconName` type in consumer code to ensure type safety.
+Import the `IconName` type in consumer code to ensure type safety.
 ```typescript
 // In consumer code
 import type { IconName } from '@canonical/ds-assets';
@@ -286,8 +287,7 @@ export interface ComponentProps {
 }
 ```
 
-(Do) Use `Pick` to restrict choices from `IconName` when necessary.
-
+Use `Pick` to restrict choices from `IconName` when necessary.
 ```typescript
 // In consumer code
 import type { IconName } from '@canonical/ds-assets';
@@ -299,7 +299,7 @@ export interface ComponentProps {
 
 ### Don't
 
-(Don't) Define icon name types or values on the consumer side.
+Define icon name types or values on the consumer side.
 ```typescript
 // Bad: String literal type defined in consumer code
 type ComponentIconName = "warning" | "search";
@@ -309,7 +309,7 @@ export interface ComponentProps {
 }
 ```
 
-(Don't) Use a generic `string` type for icon names.
+Use a generic `string` type for icon names.
 ```typescript
 // Bad: No type safety for icon names
 export interface ComponentProps {
@@ -317,7 +317,7 @@ export interface ComponentProps {
 }
 ```
 
-(Don't) Maintain separate type and value definitions.
+Maintain separate type and value definitions.
 ```typescript
 // Bad: Duplication of icon names
 const ICONS = ["warning", "search"];
@@ -332,7 +332,7 @@ Each icon concept must have exactly one SVG file. Size and theme variants are no
 
 ### Do
 
-(Do) Use a single SVG file for each icon and control its size and color with CSS.
+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">
@@ -340,8 +340,7 @@ Each icon concept must have exactly one SVG file. Size and theme variants are no
     <path fill="currentColor" d="..." />
   </g>
 </svg>
-```
-```css
+
 /* CSS usage */
 .small-icon { font-size: 1em; } /* 16px */
 .large-icon { font-size: 2em; } /* 32px */
@@ -350,14 +349,14 @@ Each icon concept must have exactly one SVG file. Size and theme variants are no
 
 ### Don't
 
-(Don't) Create multiple files for different icon sizes.
+Create multiple files for different icon sizes.
 ```
 warning.svg
 warning-small.svg
 warning-large.svg
 ```
 
-(Don't) Create multiple files for different themes.
+Create multiple files for different themes.
 ```
 warning.svg
 warning-dark.svg

package/docs/index.md

@@ -4,9 +4,10 @@ Standards documentation generated from the code-standards ontology.
 
 ## Categories
 
-- [Code](./code.md) (11)
+- [Code](./code.md) (7)
 - [CSS](./css.md) (9)
 - [Icons](./icons.md) (8)
+- [Packaging](./packaging.md) (7)
 - [React](./react.md) (14)
 - [Rust](./rust.md) (11)
 - [Storybook](./storybook.md) (9)