Illicon

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { DotGridRenderOptions } from "@coreai-ds/react-components";
import { iconToDotGrid } from "@coreai-ds/react-components";
import type { FluentIcon } from "@fluentui/react-icons";
import * as React from 'react';
import { Text } from "@coreai-ds/react-components";
import { Illicon } from "@coreai-ds/react-components";
import { Agents20Filled } from "@fluentui/react-icons";

type SamplingProps = DotGridRenderOptions & {
    multiplier: number;
};

function ConvertedIllicon({ icon, multiplier, convert = iconToDotGrid, ...props }: DotGridRenderOptions & {
    icon: FluentIcon;
    multiplier?: number;
    'aria-label'?: string;
    convert?: typeof iconToDotGrid;
}) {
    const [sample, setSample] = React.useState<{
        icon: FluentIcon;
        multiplier?: number;
        convert: typeof iconToDotGrid;
        value: Awaited<ReturnType<typeof iconToDotGrid>> | Error;
    }>();
    React.useEffect(() => {
        let active = true;
        void convert(icon, { multiplier }).then((value) => {
            if (active)
                setSample({ icon, multiplier, convert, value });
        }, (error: unknown) => {
            if (active) {
                setSample({
                    icon,
                    multiplier,
                    convert,
                    value: error instanceof Error ? error : new Error(String(error)),
                });
            }
        });
        return () => {
            active = false;
        };
    }, [icon, multiplier, convert]);
    if (!sample ||
        sample.icon !== icon ||
        sample.multiplier !== multiplier ||
        sample.convert !== convert) {
        return <Text role="status">Converting illustration...</Text>;
    }
    if (sample.value instanceof Error) {
        return <Text role="alert">{sample.value.message}</Text>;
    }
    return <Illicon {...props} data={sample.value}/>;
}

export const Default = (args: SamplingProps) => (<ConvertedIllicon {...args} icon={Agents20Filled} aria-label="Agents illustration"/>);

export default function Example() { return <Default {...{ multiplier: 2, radius: 1, pitch: 5 }} />; }

Illicon renders saved dot-grid occupancy as SVG circles. Grid data contains only equal-length, nonempty rows of 0s and 1s. Empty rows and columns, including borders, are preserved. Height is the number of rows; width is the length of a row.

import { Illicon, type DotGridData } from '@coreai-ds/react-components';

const plus: DotGridData = {
  rows: ['00000', '00100', '01110', '00100', '00000'],
};

<Illicon data={plus} radius={1} pitch={5} aria-label="Add" />;

Pixel sizing and alignment

Radius and pitch are rendering settings in CSS pixels, not occupancy data. Pitch is the center-to-center distance between cells. The default radius is 1 and pitch is 5, producing 2px dots with 3px gaps. Both must be positive and finite; radius cannot exceed half the pitch.

The SVG renders at columns * pitch by rows * pitch CSS pixels. There is no independent size for grids: a 2px circle stays 2px when sampling resolution or pitch changes. Grid SVGs do not stretch or flex-shrink to fit their wrapper.

When pitch and circle diameter are whole pixels, circle bounding edges align to integer SVG coordinates. This works for even and odd pitches and diameters. For example, 2px circles with pitch 5 have centers at 2, 7, 12, rather than 2.5, 7.5, 12.5. If the unused space in a cell is odd, one extra pixel remains on the trailing side. The complete grid artboard, including empty borders, is retained.

Fractional pitch and diameter remain supported; those settings keep centered geometry without snapping. Curves still need anti-aliasing. Pixel alignment is local to the SVG: parent transforms, fractional positioning, zoom, and device scale can affect the final physical pixels.

Omit accessible labels for decorative artwork; use aria-label or aria-labelledby when the image conveys information. Ink follows the theme's neutral foreground color and can be overridden with CSS.

Convert an icon or SVG

Conversion is an asynchronous, browser-only preparation step, not part of rendering. Import it from the main package alongside the renderer and SVG exporter:

Recommended standard: native 20px at 2x

For new Fluent-based Illicons, use the actual native 20px icon at 2x. This produces a 40 x 40 canvas and occupancy grid. Prefer Filled icons; use Regular when the illustration needs an outline. Do not resize a 16px or 24px variant to imitate the 20px source.

Keep the default radius of 1px and pitch of 5px unless the design needs a different rendering treatment. This gives a 200 x 200px illustration with 2px dots. Save the occupancy after preparation; applications need not run conversion each time the illustration renders.

import { Scales20Filled } from '@fluentui/react-icons';
import { iconToDotGrid } from '@coreai-ds/react-components';

const scales = await iconToDotGrid(Scales20Filled, { multiplier: 2 });
// multiplier: 2 is the default, so omitting the options gives the same grid.
// Save as JSON or reuse the result. Pass scales to <Illicon data={scales} />.

Source coordinates on half-pixels become whole pixels at 2x. Curves and other fractional geometry can still anti-alias; this is not a guarantee of sharpness for every source.

Other sampling settings

The converter reads source dimensions from the SVG's viewBox, not its component name or display size. Without a viewBox it uses numeric/px width and height. multiplier defaults to 2 and can be any whole number from 1 to 256, provided the resulting dimensions fit the 256-cell limit. Other native sizes and multipliers remain supported for custom needs and visual testing; they do not replace the recommended 20px-at-2x standard:

Native icon	1x grid	2x grid	3x grid
16 x 16	16 x 16	32 x 32	48 x 48
20 x 20	20 x 20	40 x 40	60 x 60
24 x 24	24 x 24	48 x 48	72 x 72

import { Heart16Regular } from '@fluentui/react-icons';

const outline = await iconToDotGrid(Heart16Regular, { multiplier: 3 });
// 48 x 48 cells.

For arbitrary grid sizes, use explicit columns and/or rows instead of multiplier. These remain supported; do not combine the two sampling modes. With explicit columns, omitted rows follow the source aspect ratio, rounded to whole cells. With rows alone, width still defaults to source width times 2. Fractional source dimensions times the multiplier are rounded to the nearest whole pixel, with a minimum of 1. Each output dimension must be 1-256.

The Storybook recreation comparison uses native 20px icons at 2x by default, with editable 16px/20px/24px sources and 1x-4x sampling for verification. Regular icons usually draw outlines with filled paths, so the separate stroked SVG example also tests actual SVG stroke geometry.

Sources may be Fluent icon components, React SVG elements, SVGSVGElements, or standalone SVG markup. A positive viewBox is required, or numeric/px width and height. Fractional dimensions and nonzero viewBox origins are supported.

Raster and SVG behavior

Explicit rows use the SVG's preserveAspectRatio behavior to fit the artwork into that viewport. The browser renders directly into a canvas of columns by rows pixels, one pixel per cell: a 20px icon at 1x uses a 20 x 20 raster; at 2x it uses 40 x 40. There is no larger intermediate raster or center-point subsampling. A cell is occupied when its pixel alpha reaches alphaThreshold, which defaults to 128 (approximately 50% coverage/opacity) and accepts integers from 1 to 255. Anti-aliasing and source opacity both affect alpha. This sampling is unrelated to rendering pitch or circle diameter. The output always retains every requested row and column, even when entirely empty.

This differs from the earlier fixed-24-cell default and supersampled center-point approach; regenerating data can change grid dimensions and dots near edges or thin features. Previously saved data is unchanged. Rasterizing an exported dotted SVG is not a lossless grid-data import: small dots may cover less than the threshold of a pixel. Reuse saved occupancy when exact grid preservation is required.

The browser renders static vector shapes, paths, strokes, transforms, and local definitions such as gradients, masks, and clipping paths. External styles are not captured. Local masks work as SVG attributes or inline CSS (mask or its longhands); all mask references must resolve within the source SVG. Scripts, event handlers, animation, stylesheets, text/fonts, images, external references, and unsupported SVG elements/styles are rejected. Sources are limited to 1 MiB of UTF-8 text and 10,000 elements. Conversion errors reject the promise; callers must surface them. During server rendering, use saved grid data instead.

Export SVG for Figma

import { dotGridToSvg } from '@coreai-ds/react-components';

const markup = dotGridToSvg(plus, { radius: 1, pitch: 5 });

The result is a standalone SVG document with editable circles, explicit dark ink, and the complete artboard. It uses the same circle positions as Illicon. Save or copy this markup into design tools; there is no need to maintain a second drawing by hand.

Preserve custom SVG artwork

Use the separate children mode for trusted inline SVG or an SVG component that forwards SVG props. Do not pass raw markup strings to Illicon.

<Illicon size={120} aria-label="Custom illustration">
  <svg viewBox="0 0 40 20" fill="currentColor">
    <circle cx="4.25" cy="5.75" r="1.25" />
    <path d="M10 2h12v10H10z" fill="none" stroke="currentColor" />
  </svg>
</Illicon>

Geometry is preserved, including irregular dots and hybrid illustrations. Use currentColor for theme-controlled fills and strokes; explicit colors stay unchanged. Supply either data or SVG children, not both. Radius and pitch apply only to grid data. Optional size applies only to custom SVG and preserves its aspect ratio; it does not apply to grids. Custom SVG is trusted React content, not a sanitized upload; authors must handle internal IDs correctly when artwork is rendered more than once.

Reviewed artwork

The illicons package export provides artwork metadata and original SVG image sources, not saved dot-grid data. There is no Illicon name prop. Download the original SVGs below for design tools; existing artwork is not resampled.

Agents

Download original SVG

Tags: none.

Workflows

Download original SVG

Tags: none.

Models

Download original SVG

Tags: none.

Fine-tune

Download original SVG

Tags: beaker, lab, test.

Database

Download original SVG

Tags: data, storage.

Documents

Download original SVG

Tags: file, pages.

Evaluations

Download original SVG

Tags: compare, scale.

Shield

Download original SVG

Tags: security, defence.

Lock closed

Download original SVG

Tags: lock, access, permissions.

Warning

Download original SVG

Tags: alert, error.

Globe

Download original SVG

Tags: networking, network, world.

Foundry

Download original SVG

Tags: none.

Home

Download original SVG

Tags: none.

AI Gateway

Download original SVG

Tags: none.

Contributing artwork

This directory is the source of truth for finished Illicon SVGs packaged with @coreai-ds/react-components. Storybook's Components / Illicon / Catalog makes the assets searchable and copies their original SVG markup for Figma or further editing. Its previews are 80px; original SVG artboards remain 140px.

The completed Illicon component accepts saved dot-grid data or custom inline SVG, not an artwork name. See the component guide for usage and sizing. Saved-data catalog integration is a separate step; the current illicons registry retains artwork metadata and original image sources only.

Standard for Fluent-based Illicons

Use the actual native 20px Fluent icon at 2x for new generated artwork. Prefer Filled, or Regular when an outline is intended. This produces a 40 x 40 canvas and grid. The converter's default multiplier is 2. At the default 1px radius and 5px pitch, the grid renders at 200 x 200px with 2px dots. See the component guide for conversion and saved-data usage.

This standard applies to new source-based generation, not to finished designer SVGs. Keep existing artwork and custom logos unchanged unless a replacement has been reviewed. The saved-data catalog and its generation workflow remain separate work.

Source verification

Storybook's Components / Illicon / Source Recreation Dev compares the original SVGs with candidate Fluent icons and freshly sampled grids. It is a verification story, excluded from the component MCP manifest. No original files are replaced. It starts with the recommended 20px-at-2x settings. Use the editable native-size selector to switch between the actual 16px, 20px, and 24px Fluent variants, not scaled copies of one icon. At 2x these produce 32, 40, and 48 cells. For the default 20px variant, the 1x-4x controls sample 20, 40, 60, or 80 cells. These alternatives are testing controls, not changes to the standard. The converter reads the SVG's own viewBox and applies the multiplier; the component name is not parsed. Radius and pitch affect rendering only; originals stay at their authored 140px size. Sampling renders directly at the grid resolution: a 20 x 20 canvas at 1x and a 40 x 40 canvas at 2x. Each pixel becomes one dot when its alpha reaches 128; no supersampled center point is used. The comparison also displays the actual sampling canvas before thresholding, enlarged without smoothing to match the output artboard. A fixed white backdrop makes the unchanged raster visible in both themes; gray pixels show partial alpha.

Sources use the selected native size and Filled variant, except Cube Regular for Models: Agents, Database, Document One Page Multiple, Scales, Globe, Home, Lock Closed, Shield, Warning, and the new Code illustration. Models and Shield approximate designer-modified originals. Beaker20Filled is a temporary Fine-tune candidate because Beaker Empty is not available in the installed package. Fluid20Filled is an unconfirmed Workflows candidate from silhouette matching. AI Gateway and Foundry are custom logos and remain original-only.

Add artwork

1. Check the catalog for an existing concept.

2. Export a transparent, monochrome SVG at width="140", height="140" and viewBox="0 0 140 140". Keep finished dot geometry unchanged. Check centering, visual weight, and family consistency; do not re-sample through a converter. When using an export scale control, select 100%, with background and construction-grid options disabled.

3. Save it here as a lowercase kebab-case filename, such as trash.svg.

4. Add an entry to manifest.json:

   {
     "title": "Trash",
     "file": "trash.svg",
     "tags": ["delete", "remove"],
     "author": "your-github-handle"
   }
   

5. From the repository root, run:

   npm run storybook
   

6. Open Components / Illicon / Catalog. Check search, preview, and Copy SVG. Include light/dark screenshots in your PR.

Storybook startup validates and generates the catalog automatically. If Storybook is already running, regenerate after saving the SVG and manifest:

node scripts/generate-illicons.mjs

See the repository contribution policy for setup and review and CLA requirements. Assets reach consumers in a published package release.

Manifest contract (version 1)

• title: unique, trimmed display title.
• file: unique lowercase kebab-case .svg filename in this directory.
• tags: an array of unique, trimmed, lowercase search terms; use [] when no additional keywords are useful. Do not repeat the illustration's title.
• author: the artwork creator's GitHub handle or credited name.

The filename determines the registry ID: trash.svg becomes trash. Keep filenames stable so existing registry lookups continue to work.

Suggest tags

Edit an existing entry's tags in manifest.json without changing its filename or SVG. Use relevant search terms beyond the title, or leave the array empty. Run the same checks and submit the update in a pull request.

SVG contract

The validator parses XML and rejects malformed documents, executable content, event handlers, CSS, embedded images, remote references, DOCTYPE, and processing instructions. It accepts static SVG shapes, groups, definitions, text-only titles/descriptions, and local use references directly to shapes. References to groups or other use elements are not supported. Files must be regular files, at most 1 MiB, and at most 20,000 elements.

Supported paints are none, currentColor, black, white, and hex colors. Transforms and original path/circle geometry are preserved. Export unsupported effects as static vector shapes before submitting; the validator never rewrites artwork. Automated checks are not a visual or accessibility review: maintainers still verify dot spacing, size, contrast, centering, meaningful names/tags, and consistency with the illustration family.

The manifest and all listed SVGs are validated before generating the typed artwork registry. Missing files, duplicate filenames/titles, missing authors, invalid tags, unsafe SVGs, and unlisted SVG files fail validation. The registry embeds byte-identical SVGs as image sources, avoiding asset-path configuration and keeping SVG IDs isolated when an illustration appears more than once.

interface IlliconProps {
  /**
   * Trusted inline SVG. Use currentColor for theme-aware paint; geometry is not rewritten.
   */
  children?: ReactElement<SVGProps<SVGSVGElement>, string | JSXElementConstructor<any>>;

  className?: string;

  data?: DotGridData;

  /**
   * Center-to-center distance between cells. Defaults to 5.
   */
  pitch?: number;

  /**
   * Circle radius. Defaults to 1; must fit within half the pitch.
   */
  radius?: number;

  ref?: Ref<HTMLSpanElement>;

  /**
   * Display width for custom SVG artwork only. Grids use cells times pitch.
   */
  size?: number;

  style?: CSSProperties;
}

declare function iconToDotGrid(source: IconToDotGridSource, options?: IconToDotGridOptions): Promise<DotGridData>;

declare function dotGridToSvg(data: DotGridData, options?: DotGridRenderOptions): string;