@canonical/code-standards 0.1.0 → 0.1.1

package/data/icons.ttl

@@ -15,32 +15,33 @@ cs:IconFileStorage a cs:CodeStandard ;
     cs:name "icons/file/storage" ;
     cs:hasCategory cs:IconsCategory ;
     cs:description "Each icon shall be stored as a single SVG file in the `icons/` directory." ;
-    cs:dos """
-(Do) Store each icon as an individual SVG file in the designated `icons/` directory.
-```
+    cs:do [
+        cs:description "Store each icon as an individual SVG file in the designated `icons/` directory." ;
+        cs:code """
 icons/
   ├── warning.svg
   ├── search.svg
   └── github.svg
-```
-""" ;
-    cs:donts """
-(Don't) Store icons in nested directories or use incorrect file extensions.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Store icons in nested directories or use incorrect file extensions." ;
+        cs:code """
 icons/
   ├── variants/
   │   └── warning-dark.svg
   ├── warning/
   │   └── index.svg
   └── warning.svg.txt
-```
-
-(Don't) Combine multiple icons into a single SVG file.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Combine multiple icons into a single SVG file." ;
+        cs:code """
 icons/
   └── all-icons.svg
-```
-""" .
+    """
+    ] .
 
 # Icon File Naming Standard
 cs:IconFileNaming a cs:CodeStandard ;
@@ -49,49 +50,52 @@ cs:IconFileNaming a cs:CodeStandard ;
     cs:description """Icon files must:
 - Use kebab-case naming
 - Use semantic identifiers""" ;
-    cs:dos """
-(Do) Use kebab-case and a semantic identifier for the icon file name.
-```
+    cs:do [
+        cs:description "Use kebab-case and a semantic identifier for the icon file name." ;
+        cs:code """
 warning.svg
 user-profile.svg
 arrow-down.svg
-```
-""" ;
-    cs:donts """
-(Don't) Include size, theme, or redundant suffixes in the file name.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Include size, theme, or redundant suffixes in the file name." ;
+        cs:code """
 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.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use non-semantic or ambiguous names that do not describe the icon." ;
+        cs:code """
 icon1.svg
 shape.svg
-```
-""" .
+    """
+    ] .
 
 # Icon Group Element Standard
 cs:IconGroupElement a cs:CodeStandard ;
     cs:name "icons/svg/group-element" ;
     cs:hasCategory cs:IconsCategory ;
     cs:description "Each icon's SVG markup must contain a single `<g>` element with an `id` matching the filename (without `.svg`)." ;
-    cs:dos """
-(Do) Include a single `<g>` element with an `id` that matches the filename.
-```svg
+    cs:do [
+        cs:description "Include a single `<g>` element with an `id` that matches the filename." ;
+        cs:language "svg" ;
+        cs:code """
 <!-- warning.svg -->
 <svg>
   <g id="warning">
     <!-- icon paths -->
   </g>
 </svg>
-```
-""" ;
-    cs:donts """
-(Don't) Use multiple `<g>` elements or an `id` that does not match the filename.
-```svg
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use multiple `<g>` elements or an `id` that does not match the filename." ;
+        cs:language "svg" ;
+        cs:code """
 <!-- warning.svg -->
 <svg>
   <g id="icon-group">
@@ -101,115 +105,126 @@ cs:IconGroupElement a cs:CodeStandard ;
     <!-- alternate paths -->
   </g>
 </svg>
-```
-""" .
+    """
+    ] .
 
 # Icon ViewBox Standard
 cs:IconViewBox a cs:CodeStandard ;
     cs:name "icons/svg/viewbox" ;
     cs:hasCategory cs:IconsCategory ;
     cs:description "All icon SVGs must use a `viewBox` of `0 0 16 16`." ;
-    cs:dos """
-(Do) Set the `viewBox` attribute to `0 0 16 16` in the `<svg>` element.
-```svg
+    cs:do [
+        cs:description "Set the `viewBox` attribute to `0 0 16 16` in the `<svg>` element." ;
+        cs:language "svg" ;
+        cs:code """
 <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'>
   <g id="icon">
     <!-- Icon content scaled to 16x16 -->
   </g>
 </svg>
-```
-""" ;
-    cs:donts """
-(Don't) Use a `viewBox` with dimensions other than `16 16`.
-```svg
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use a `viewBox` with dimensions other than `16 16`." ;
+        cs:language "svg" ;
+        cs:code """
 <!-- Bad: Different viewBox size -->
 <svg viewBox="0 0 24 24">
   <g id="icon">...</g>
 </svg>
-```
-
-(Don't) Use a non-square `viewBox`.
-```svg
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use a non-square `viewBox`." ;
+        cs:language "svg" ;
+        cs:code """
 <!-- Bad: Non-square viewBox -->
 <svg viewBox="0 0 16 24">
   <g id="icon">...</g>
 </svg>
-```
-
-(Don't) Omit the `viewBox` attribute.
-```svg
+    """
+    ] ;
+    cs:dont [
+        cs:description "Omit the `viewBox` attribute." ;
+        cs:language "svg" ;
+        cs:code """
 <!-- Bad: Missing viewBox -->
 <svg width="16" height="16">
   <g id="icon">...</g>
 </svg>
-```
-""" .
+    """
+    ] .
 
 # Icon Color Usage Standard
 cs:IconColorUsage a cs:CodeStandard ;
     cs:name "icons/svg/color-usage" ;
     cs:hasCategory cs:IconsCategory ;
     cs:description "Icon must use `fill` with `currentColor` for their paths and shapes." ;
-    cs:dos """
-(Do) Use `currentColor` for the `fill` of paths in non-branded icons.
-```svg
+    cs:do [
+        cs:description "Use `currentColor` for the `fill` of paths in non-branded icons." ;
+        cs:language "svg" ;
+        cs:code """
 <!-- Non-branded icon -->
 <svg viewBox="0 0 16 16">
   <g id="search">
     <path fill="currentColor" d="..." />
   </g>
 </svg>
-```
-""" ;
-    cs:donts """
-(Don't) Use hard-coded colors in icons.
-```svg
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use hard-coded colors in icons." ;
+        cs:language "svg" ;
+        cs:code """
 <path fill="#000000" d="..." />
-```
-
-(Don't) Use `opacity` to create different shades of a color.
-```svg
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use `opacity` to create different shades of a color." ;
+        cs:language "svg" ;
+        cs:code """
 <path fill="currentColor" opacity="0.5" d="..." />
-```
-""" .
+    """
+    ] .
 
 # Icon Variant Standard
 cs:IconVariant a cs:CodeStandard ;
     cs:name "icons/variant/single-file" ;
     cs:hasCategory cs:IconsCategory ;
     cs:description "Each icon concept must have exactly one SVG file. Size and theme variants are not allowed." ;
-    cs:dos """
-(Do) Use a single SVG file for each icon and control its size and color with CSS.
-```svg
+    cs:do [
+        cs:description "Use a single SVG file for each icon and control its size and color with CSS." ;
+        cs:language "svg" ;
+        cs:code """
 <!-- 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); }
-```
-""" ;
-    cs:donts """
-(Don't) Create multiple files for different icon sizes.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create multiple files for different icon sizes." ;
+        cs:code """
 warning.svg
 warning-small.svg
 warning-large.svg
-```
-
-(Don't) Create multiple files for different themes.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create multiple files for different themes." ;
+        cs:code """
 warning.svg
 warning-dark.svg
 warning-light.svg
-```
-""" .
+    """
+    ] .
 
 # Icon Type Safety Standard
 cs:IconTypeSafety a cs:CodeStandard ;
@@ -219,9 +234,10 @@ cs:IconTypeSafety a cs:CodeStandard ;
 - Maintained in a type-safe constant array
 - Used to generate the `IconName` type
 - Defined in the icon exporter package""" ;
-    cs:dos """
-(Do) Define a constant array of icon names and derive the `IconName` type from it in the icon exporter package.
-```typescript
+    cs:do [
+        cs:description "Define a constant array of icon names and derive the `IconName` type from it in the icon exporter package." ;
+        cs:language "typescript" ;
+        cs:code """
 // In the icon exporter package
 export const ICON_NAMES = [
   "warning",
@@ -230,65 +246,74 @@ export const ICON_NAMES = [
 ] as const;
 
 export type IconName = typeof ICON_NAMES[number];
-```
-
-(Do) Import the `IconName` type in consumer code to ensure type safety.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Import the `IconName` type in consumer code to ensure type safety." ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Use `Pick` to restrict choices from `IconName` when necessary." ;
+        cs:language "typescript" ;
+        cs:code """
 // In consumer code
 import type { IconName } from '@canonical/ds-assets';
 
 export interface ComponentProps {
   icon: Pick<IconName, "warning" | "search">;
 }
-```
-""" ;
-    cs:donts """
-(Don't) Define icon name types or values on the consumer side.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Define icon name types or values on the consumer side." ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use a generic `string` type for icon names." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: No type safety for icon names
 export interface ComponentProps {
     icon: string;
 }
-```
-
-(Don't) Maintain separate type and value definitions.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Maintain separate type and value definitions." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: Duplication of icon names
 const ICONS = ["warning", "search"];
 type IconName = "warning" | "search";
-```
-""" .
+    """
+    ] .
 
 # Icon Mask Usage Standard
 cs:IconMaskUsage a cs:CodeStandard ;
     cs:name "icons/svg/mask-usage" ;
     cs:hasCategory cs:IconsCategory ;
     cs:description "Icons may use SVG masks to negate or partially negate paths, enabling advanced visual effects such as cutouts and overlays." ;
-    cs:dos """
-(Do) Use SVG <mask> elements to create negative space or overlays in icons.
-Example:
-```svg
+    cs:do [
+        cs:description "Use SVG <mask> elements to create negative space or overlays in icons.
+Example" ;
+        cs:language "svg" ;
+        cs:code """
 <svg width='16' height='16' xmlns='http://www.w3.org/2000/svg'>
   <defs>
     <mask id="error-mask">
@@ -300,60 +325,71 @@ Example:
     <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
+    """
+    ] ;
+    cs:do [
+        cs:description "Use <rect> with fill="white" to define the mask area, and <path> with fill="black" to subtract shapes.
+Example" ;
+        cs:language "svg" ;
+        cs:code """
 <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
+    """
+    ] ;
+    cs:do [
+        cs:description "Use opacity on mask paths to achieve partial negation (e.g., faded or semi-transparent cutouts).
+Example" ;
+        cs:language "svg" ;
+        cs:code """
 <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
+    """
+    ] ;
+    cs:do [
+        cs:description "Reference the mask in the icon's main shape using mask="url(#mask-id)".
+Example" ;
+        cs:language "svg" ;
+        cs:code """
 <circle fill='currentColor' cx='8' cy='8' r='7' mask="url(#mask-id)"/>
-```
-""" ;
-    cs:donts """
-(Don't) Use masks without clear purpose or visual benefit.
-Example:
-```svg
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use masks without clear purpose or visual benefit.
+Example" ;
+        cs:language "svg" ;
+        cs:code """
 <!-- 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "use non-semantic mask ids or omit mask references in the main shape.
+Example" ;
+        cs:language "svg" ;
+        cs:code """
 <!-- 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "rely on masks for simple icons that do not require negative space or overlays.
+Example" ;
+        cs:language "svg" ;
+        cs:code """
 <!-- 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)"/>
-```
-""" .
+    """
+    ] .