@canonical/code-standards 0.1.0

package/data/icons.ttl

@@ -0,0 +1,359 @@
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# Icons Category
+cs:IconsCategory a cs:Category ;
+    rdfs:label "Icons"@en ;
+    rdfs:comment "Standards for icon development and implementation"@en ;
+    cs:slug "icons" .
+
+# Icon File Storage Standard
+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.
+```
+icons/
+  ├── warning.svg
+  ├── search.svg
+  └── github.svg
+```
+""" ;
+    cs:donts """
+(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
+```
+""" .
+
+# Icon File Naming Standard
+cs:IconFileNaming a cs:CodeStandard ;
+    cs:name "icons/file/naming" ;
+    cs:hasCategory cs:IconsCategory ;
+    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.
+```
+warning.svg
+user-profile.svg
+arrow-down.svg
+```
+""" ;
+    cs:donts """
+(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
+```
+""" .
+
+# 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
+<!-- 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
+<!-- warning.svg -->
+<svg>
+  <g id="icon-group">
+    <!-- icon paths -->
+  </g>
+  <g id="warning-alt">
+    <!-- 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
+<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
+<!-- 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>
+```
+""" .
+
+# 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
+<!-- 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
+<path fill="#000000" d="..." />
+```
+
+(Don't) Use `opacity` to create different shades of a color.
+```svg
+<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
+<!-- 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.
+```
+warning.svg
+warning-small.svg
+warning-large.svg
+```
+
+(Don't) Create multiple files for different themes.
+```
+warning.svg
+warning-dark.svg
+warning-light.svg
+```
+""" .
+
+# Icon Type Safety Standard
+cs:IconTypeSafety a cs:CodeStandard ;
+    cs:name "icons/type-safety/definition" ;
+    cs:hasCategory cs:IconsCategory ;
+    cs:description """Icon names must be:
+- 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
+// 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">;
+}
+```
+""" ;
+    cs:donts """
+(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";
+```
+""" .
+
+# 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
+<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)"/>
+```
+""" ;
+    cs:donts """
+(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)"/>
+```
+""" .