first commit

2026-05-18 15:53:59 +03:30
commit 2c100028a1
534 changed files with 94240 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Adding New SVG Icons (Sufi Icons)
+
+Sufi Icons (si) are the only icon set used in the platform. All icons live in a single registry and are rendered by `SbIcon`. This guide explains how to add a new SVG icon.
+
+## Where icons are defined
+
+| File | Purpose |
+|------|---------|
+| `SufiChain.SufiBlazor/Icons/SiIconCategory.cs` | Enum of categories (Navigation, Actions, Media, Files, etc.) |
+| `SufiChain.SufiBlazor/Icons/SiIconMetadata.cs` | Record: Name, Category, Description, Svg |
+| `SufiChain.SufiBlazor/Icons/SufiIcons.cs` | Static registry: dictionary of all icons, `GetIcon`, `GetSvg`, `GetByCategory`, `Search` |
+| `SufiChain.SufiBlazor/Components/Common/SbIcon.razor` | Renders icon by name via `SufiIcons.GetSvg(Name)` — **do not add icons here** |
+
+Icons are **not** defined in `SbIcon.razor`. They are defined only in `SufiIcons.cs` inside `CreateIconRegistry()`.
+
+## SVG contract (required for consistency)
+
+All new outline-style icons must follow this contract so they scale and theme correctly:
+
+- **ViewBox**: `viewBox="0 0 24 24"`
+- **Fill**: `fill="none"` for outline icons
+- **Stroke**: `stroke="currentColor"` and `stroke-width="2"`
+- **Caps/joins**: `stroke-linecap="round"` and `stroke-linejoin="round"`
+- **No scripts, external refs, or editor metadata**
+
+Example outline SVG:
+
+```xml
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M6 9l6 6 6-6"/>
+</svg>
+```
+
+For solid/filled icons (e.g. dots, filled shapes), use `fill="currentColor"` and no stroke. The registry defines constants `SvgOutlineAttrs` and `SvgSolidAttrs` in `SufiIcons.cs` — use them when building the SVG string in code.
+
+## Step-by-step: add a new icon
+
+### 1. Choose a name and category
+
+- **Name**: kebab-case (e.g. `file-pdf`, `user-plus`). Must be unique.
+- **Category**: Pick one of the values in `SiIconCategory` (e.g. `SiIconCategory.Files`, `SiIconCategory.Actions`). If you need a new category, add it to the enum in `SiIconCategory.cs` first.
+
+### 2. Add the icon to the registry
+
+Open `sufi-platform/src/modules/sufi-blazor/src/SufiChain.SufiBlazor/Icons/SufiIcons.cs` and find the method `CreateIconRegistry()`. Add a new entry to the dictionary:
+
+```csharp
+["your-icon-name"] = new("your-icon-name", SiIconCategory.YourCategory, "Short description for search/accessibility",
+    $"<svg {SvgOutlineAttrs}><path d=\"M...\"/></svg>"),
+```
+
+- Use `SvgOutlineAttrs` for stroke-based icons or `SvgSolidAttrs` for fill-only icons.
+- Escape double quotes inside the SVG string (e.g. `\"` for attributes).
+- Place the entry in the appropriate comment block (e.g. `// ========== File Icons ==========`) so the file stays organized.
+
+### 3. Verify in the demo
+
+Run the SufiBlazorDemo app and open the Icon page (e.g. `/components/icon`). Your icon should appear in the grid and in search. You can filter by category to confirm it’s in the right group.
+
+### 4. Use the icon in the app
+
+Use the same name (with or without the `si-` prefix) in `SbIcon`:
+
+```razor
+<SbIcon Name="your-icon-name" />
+```
+
+For menu items and other string-based icon fields, use the same name:
+
+```csharp
+icon: "your-icon-name"
+```
+
+## Naming conventions
+
+- Use **kebab-case**: `chevron-down`, `folder-open`, `shield-check`.
+- Prefer **short, clear names** that match common icon sets (e.g. Lucide/Feather) for easier recognition.
+- **No** `si-` prefix in the registry key; the component accepts both `"home"` and `"si-home"` and normalizes internally.
+
+## Optional: AI-generated icons
+
+If you generate SVG with an AI or tooling:
+
+1. Enforce the same contract (24×24 viewBox, stroke/fill, round caps/joins, `currentColor`).
+2. Strip scripts, external references, and metadata.
+3. Prefer optimizing with SVGO (or similar) before pasting into the registry, and avoid aggressive rounding of path data.
+
+The file `.cursor/plans/icons-list.csv` in the repo contains icon names, categories, and prompts used for the initial pack; you can use it as a reference for naming and categories.
+
+## Summary checklist
+
+- [ ] Name is kebab-case and unique.
+- [ ] Category exists in `SiIconCategory` (add enum value if needed).
+- [ ] New entry added in `SufiIcons.CreateIconRegistry()` with correct SVG.
+- [ ] SVG follows the contract (viewBox, stroke/fill, round caps/joins, `currentColor`).
+- [ ] Icon appears and is searchable on the demo Icon page.
+- [ ] Usage in app is via `<SbIcon Name="your-icon-name" />` or `icon: "your-icon-name"` only.