diff --git a/.changeset/docs-icon-design-guide.md b/.changeset/docs-icon-design-guide.md new file mode 100644 index 000000000..d1a8191db --- /dev/null +++ b/.changeset/docs-icon-design-guide.md @@ -0,0 +1,5 @@ +--- +"@tabler/docs": minor +--- + +Added the Icon design guide page to the Tabler Icons docs, with the SVG format, naming rules and icon requests. diff --git a/.github/workflows/calibreapp-image-actions.yml b/.github/workflows/calibreapp-image-actions.yml index 8b12d7207..713cda45d 100644 --- a/.github/workflows/calibreapp-image-actions.yml +++ b/.github/workflows/calibreapp-image-actions.yml @@ -29,3 +29,6 @@ jobs: uses: calibreapp/image-actions@26d5b54006db4da7a1b29903f33404a6f77b58cf # main, 2026-09-02 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # docs images go through astro:assets, which makes the webp files at build + # time; lossy PNG compression here only degrades the source + ignorePaths: 'node_modules/**,docs/images/**' diff --git a/docs/components/Picture.astro b/docs/components/Picture.astro new file mode 100644 index 000000000..3ee134d40 --- /dev/null +++ b/docs/components/Picture.astro @@ -0,0 +1,26 @@ +--- +// An image in a framed box: the same surface, border and radius as an +// demo, so pictures and demos look alike on a page. Give the image a transparent +// background, or the exact `bg-surface-secondary` color so it blends into the box. +// With `srcDark` the box swaps images with the theme. +// The box draws the frame, so the images drop the border and radius that +// `.prose > figure > img` gives them. +import type { ImageMetadata } from 'astro' +import { Image } from 'astro:assets' + +interface Props { + src: ImageMetadata + /** version shown in dark mode; without it `src` is shown in both modes */ + srcDark?: ImageMetadata + alt: string + /** display width in pixels; the image is also rendered at 2x */ + width?: number +} + +const { src, srcDark, alt, width = 480 } = Astro.props +--- + +
+ {alt} + {srcDark && {alt}} +
diff --git a/docs/content/icons/design-guide.mdx b/docs/content/icons/design-guide.mdx new file mode 100644 index 000000000..2576c6d9d --- /dev/null +++ b/docs/content/icons/design-guide.mdx @@ -0,0 +1,155 @@ +--- +title: Icon design guide +summary: The rules every Tabler icon follows — a 24×24 canvas, a 2 px centered stroke, round joins and caps, and fixed padding, radius and spacing. It also covers the SVG format, icon names and how to request a new icon. +description: Design rules for Tabler Icons. Canvas size, stroke, corner radius and spacing, plus the SVG format, naming and icon requests. +--- + +import Picture from '@components/Picture.astro' +import guide1 from '../../images/icons-guide/guide-1.png' +import guide1Dark from '../../images/icons-guide/guide-1-dark.png' +import guide2 from '../../images/icons-guide/guide-2.png' +import guide2Dark from '../../images/icons-guide/guide-2-dark.png' +import guide3 from '../../images/icons-guide/guide-3.png' +import guide3Dark from '../../images/icons-guide/guide-3-dark.png' +import guide4 from '../../images/icons-guide/guide-4.png' +import guide4Dark from '../../images/icons-guide/guide-4-dark.png' +import guide5 from '../../images/icons-guide/guide-5.png' +import guide5Dark from '../../images/icons-guide/guide-5-dark.png' +import guide6 from '../../images/icons-guide/guide-6.png' +import guide6Dark from '../../images/icons-guide/guide-6-dark.png' +import guide7 from '../../images/icons-guide/guide-7.png' +import guide7Dark from '../../images/icons-guide/guide-7-dark.png' +import guide8 from '../../images/icons-guide/guide-8.png' +import guide8Dark from '../../images/icons-guide/guide-8-dark.png' +import guide9 from '../../images/icons-guide/guide-9.png' +import guide9Dark from '../../images/icons-guide/guide-9-dark.png' +import guide10 from '../../images/icons-guide/guide-10.png' +import guide10Dark from '../../images/icons-guide/guide-10-dark.png' +import guide11 from '../../images/icons-guide/guide-11.png' +import guide11Dark from '../../images/icons-guide/guide-11-dark.png' +import guide12 from '../../images/icons-guide/guide-12.png' +import guide12Dark from '../../images/icons-guide/guide-12-dark.png' +import guide13 from '../../images/icons-guide/guide-13.png' +import guide13Dark from '../../images/icons-guide/guide-13-dark.png' + +All Tabler Icons follow the same set of design rules. This keeps the collection consistent, so icons look like they belong together at any size. Follow these rules when you draw your own icons to use next to Tabler Icons, or when you sketch an icon for a [request](#request-an-icon). + +## Canvas + +Design every icon on a 24×24 pixel canvas. This is the standard size for most icon sets and the one best supported in web and mobile apps. The same canvas for every icon keeps the set uniform and easy to scale. + + + +Start from the keyline shapes: a circle, a square, a wide rectangle and a tall rectangle. Draw a round object on the circle, a square one on the square and a wide or tall one on a rectangle. Different shapes then look the same size next to each other. The lines mark the center of the stroke. + + + +## Padding + +Leave at least 1 pixel of padding between the icon and the edge of the canvas. The icon then never touches its container and stays clear at small sizes. + + + +## Stroke width + +Draw icons with a 2 pixel stroke. The same line weight across the set makes icons look balanced and easy to read. + + + +## Round joins + +Use round joins where lines meet. Corners between lines and curves then look smooth and match the rest of the set. + + + +## Round caps + +Use round caps at the open ends of lines. They give icons a soft, friendly look. + + + +## Centered strokes + +Center the stroke on the path, not inside or outside it. This keeps shapes symmetric and their size predictable. + + + +## Corner radius + +Give shapes such as rectangles a 2 pixel corner radius. Soft corners match the round joins and caps. + + + +## Spacing + +Keep 2 pixels of space between separate elements of an icon. The parts stay distinct and the icon stays readable at small sizes. + + + +## Accessibility + +Make icons easy to tell apart, including for people with low vision. Use shapes with clear contrast and avoid icons that differ only in small details. + + + +## Export to SVG + +Save every icon as a plain SVG file. Put the stroke settings on the `` element, so the icon takes its color from the text around it and can be restyled with CSS: + +- Set `width`, `height` and `viewBox` to `24` and `0 0 24 24`. +- Set `fill="none"` and `stroke="currentColor"`. Do not use fixed colors. +- Set `stroke-width="2"`, `stroke-linecap="round"` and `stroke-linejoin="round"`. +- Draw every shape as a ``, including circles and rectangles. +- Remove groups, transforms, masks, clip paths and IDs that your design tool adds. + +A circle is two arcs and a rounded square is four lines joined by four arcs. The marks show the points where the path changes direction. + + + +This is the `ghost` icon from the set: + +```html + + + + + + +``` + +A dot, such as an eye, is a very short line (`l.01 0`). The round caps turn it into a 2 pixel circle. + + + +## Naming + +Name icons after what they show, not after what they do in one app. Use lowercase words joined with hyphens, and put the main object first: + +- `arrow-left`, `alert-circle`, `user-plus`: object first, then the shape or detail. +- `bell-off`, `folder-plus`, `circle-check`: common suffixes for a crossed out, added or checked version. +- `brand-github`: every logo starts with `brand-`. +- `ghost-2`, `ghost-3`: a number marks another drawing of the same object. + +A suffix adds a small mark to the base icon. The base shape leaves room for it, usually in the bottom right corner, and a slash for `-off` crosses the whole icon. + + + +## Request an icon + +If an icon is missing from the set, request it in the [Tabler Icons issue tracker](https://github.com/tabler/tabler-icons/issues/new?template=01-icon_request.yml). First search [tabler.io/icons](https://tabler.io/icons) and the existing issues, including closed ones. If someone already asked for the same icon, add a 👍 to that issue instead. + +The request form asks for: + +- **Icon name**: what the icon should show. +- **Use cases**: at least two real situations where you need it. +- **Design ideas**: simple examples from other icon sets, or your own sketch drawn with the rules on this page. diff --git a/docs/content/icons/index.mdx b/docs/content/icons/index.mdx index 6e626e9c3..57d1664f7 100644 --- a/docs/content/icons/index.mdx +++ b/docs/content/icons/index.mdx @@ -30,6 +30,8 @@ The same icon set is distributed in several forms, so you can pick the one that - **[Static files](/icons/static-files)**: every icon as a standalone [SVG](/icons/static-files/svg), [PNG](/icons/static-files/png) or [PDF](/icons/static-files/pdf) file, for design tools and non-web use. - **[Figma plugin](/icons/plugins/figma)**: insert icons directly into your Figma designs. +To draw your own icons that match the set, or to request a new one, see the [icon design guide](/icons/design-guide). + ## Quick start In a framework project, install the package for your stack, for example React: diff --git a/docs/content/icons/plugins/figma.mdx b/docs/content/icons/plugins/figma.mdx index e8fdb1312..d945a9ee9 100644 --- a/docs/content/icons/plugins/figma.mdx +++ b/docs/content/icons/plugins/figma.mdx @@ -14,4 +14,6 @@ The Tabler Icons Figma plugin puts the whole icon set inside Figma. You search f Install the plugin from the Figma community and open it from the plugins menu in your file. Type a keyword to search, then click an icon to insert it. Once it's in the design, you can change its size, color and stroke width. +To draw your own icons next to the inserted ones, follow the [icon design guide](/icons/design-guide). It lists the canvas, stroke and spacing rules the set uses. + diff --git a/docs/content/ui/components/icon.mdx b/docs/content/ui/components/icon.mdx index 8d44818e4..9a653b580 100644 --- a/docs/content/ui/components/icon.mdx +++ b/docs/content/ui/components/icon.mdx @@ -32,7 +32,7 @@ classnames: import Example from '@components/Example.astro'; import Icon from '@ui/Icon.astro'; -The [Tabler Icons library](https://tabler.io/icons) has over 5,000 icons under the MIT license, so you can use them in private and commercial projects. +The [Tabler Icons library](https://tabler.io/icons) has over 5,000 icons under the MIT license, so you can use them in private and commercial projects. If an icon is missing, [request it](/icons/design-guide#request-an-icon), or draw your own with the [icon design guide](/icons/design-guide) so it matches the set. ## Base icon diff --git a/docs/images/icons-guide/guide-1-dark.png b/docs/images/icons-guide/guide-1-dark.png new file mode 100644 index 000000000..f69ea0bd4 Binary files /dev/null and b/docs/images/icons-guide/guide-1-dark.png differ diff --git a/docs/images/icons-guide/guide-1.png b/docs/images/icons-guide/guide-1.png new file mode 100644 index 000000000..85d7057b1 Binary files /dev/null and b/docs/images/icons-guide/guide-1.png differ diff --git a/docs/images/icons-guide/guide-10-dark.png b/docs/images/icons-guide/guide-10-dark.png new file mode 100644 index 000000000..65c3248ef Binary files /dev/null and b/docs/images/icons-guide/guide-10-dark.png differ diff --git a/docs/images/icons-guide/guide-10.png b/docs/images/icons-guide/guide-10.png new file mode 100644 index 000000000..d1f49deea Binary files /dev/null and b/docs/images/icons-guide/guide-10.png differ diff --git a/docs/images/icons-guide/guide-11-dark.png b/docs/images/icons-guide/guide-11-dark.png new file mode 100644 index 000000000..6d54c4d43 Binary files /dev/null and b/docs/images/icons-guide/guide-11-dark.png differ diff --git a/docs/images/icons-guide/guide-11.png b/docs/images/icons-guide/guide-11.png new file mode 100644 index 000000000..9a73d01ac Binary files /dev/null and b/docs/images/icons-guide/guide-11.png differ diff --git a/docs/images/icons-guide/guide-12-dark.png b/docs/images/icons-guide/guide-12-dark.png new file mode 100644 index 000000000..850bddf59 Binary files /dev/null and b/docs/images/icons-guide/guide-12-dark.png differ diff --git a/docs/images/icons-guide/guide-12.png b/docs/images/icons-guide/guide-12.png new file mode 100644 index 000000000..f86621d8e Binary files /dev/null and b/docs/images/icons-guide/guide-12.png differ diff --git a/docs/images/icons-guide/guide-13-dark.png b/docs/images/icons-guide/guide-13-dark.png new file mode 100644 index 000000000..6dc91ef36 Binary files /dev/null and b/docs/images/icons-guide/guide-13-dark.png differ diff --git a/docs/images/icons-guide/guide-13.png b/docs/images/icons-guide/guide-13.png new file mode 100644 index 000000000..e606dbe96 Binary files /dev/null and b/docs/images/icons-guide/guide-13.png differ diff --git a/docs/images/icons-guide/guide-2-dark.png b/docs/images/icons-guide/guide-2-dark.png new file mode 100644 index 000000000..4a019b49b Binary files /dev/null and b/docs/images/icons-guide/guide-2-dark.png differ diff --git a/docs/images/icons-guide/guide-2.png b/docs/images/icons-guide/guide-2.png new file mode 100644 index 000000000..244270760 Binary files /dev/null and b/docs/images/icons-guide/guide-2.png differ diff --git a/docs/images/icons-guide/guide-3-dark.png b/docs/images/icons-guide/guide-3-dark.png new file mode 100644 index 000000000..a9912f0a8 Binary files /dev/null and b/docs/images/icons-guide/guide-3-dark.png differ diff --git a/docs/images/icons-guide/guide-3.png b/docs/images/icons-guide/guide-3.png new file mode 100644 index 000000000..e862987dc Binary files /dev/null and b/docs/images/icons-guide/guide-3.png differ diff --git a/docs/images/icons-guide/guide-4-dark.png b/docs/images/icons-guide/guide-4-dark.png new file mode 100644 index 000000000..96bd59c42 Binary files /dev/null and b/docs/images/icons-guide/guide-4-dark.png differ diff --git a/docs/images/icons-guide/guide-4.png b/docs/images/icons-guide/guide-4.png new file mode 100644 index 000000000..72517e00f Binary files /dev/null and b/docs/images/icons-guide/guide-4.png differ diff --git a/docs/images/icons-guide/guide-5-dark.png b/docs/images/icons-guide/guide-5-dark.png new file mode 100644 index 000000000..55db5dc89 Binary files /dev/null and b/docs/images/icons-guide/guide-5-dark.png differ diff --git a/docs/images/icons-guide/guide-5.png b/docs/images/icons-guide/guide-5.png new file mode 100644 index 000000000..1402caf81 Binary files /dev/null and b/docs/images/icons-guide/guide-5.png differ diff --git a/docs/images/icons-guide/guide-6-dark.png b/docs/images/icons-guide/guide-6-dark.png new file mode 100644 index 000000000..a11678806 Binary files /dev/null and b/docs/images/icons-guide/guide-6-dark.png differ diff --git a/docs/images/icons-guide/guide-6.png b/docs/images/icons-guide/guide-6.png new file mode 100644 index 000000000..21e18d89e Binary files /dev/null and b/docs/images/icons-guide/guide-6.png differ diff --git a/docs/images/icons-guide/guide-7-dark.png b/docs/images/icons-guide/guide-7-dark.png new file mode 100644 index 000000000..3800b0db5 Binary files /dev/null and b/docs/images/icons-guide/guide-7-dark.png differ diff --git a/docs/images/icons-guide/guide-7.png b/docs/images/icons-guide/guide-7.png new file mode 100644 index 000000000..5343325bb Binary files /dev/null and b/docs/images/icons-guide/guide-7.png differ diff --git a/docs/images/icons-guide/guide-8-dark.png b/docs/images/icons-guide/guide-8-dark.png new file mode 100644 index 000000000..8c978f916 Binary files /dev/null and b/docs/images/icons-guide/guide-8-dark.png differ diff --git a/docs/images/icons-guide/guide-8.png b/docs/images/icons-guide/guide-8.png new file mode 100644 index 000000000..bd58fdb60 Binary files /dev/null and b/docs/images/icons-guide/guide-8.png differ diff --git a/docs/images/icons-guide/guide-9-dark.png b/docs/images/icons-guide/guide-9-dark.png new file mode 100644 index 000000000..be04671c1 Binary files /dev/null and b/docs/images/icons-guide/guide-9-dark.png differ diff --git a/docs/images/icons-guide/guide-9.png b/docs/images/icons-guide/guide-9.png new file mode 100644 index 000000000..b6f2c57cb Binary files /dev/null and b/docs/images/icons-guide/guide-9.png differ diff --git a/shared/data/docs.json b/shared/data/docs.json index ba3a7ac42..022c080bd 100644 --- a/shared/data/docs.json +++ b/shared/data/docs.json @@ -556,6 +556,10 @@ "title": "Introduction", "url": "/icons" }, + { + "title": "Icon design guide", + "url": "/icons/design-guide" + }, { "title": "Libraries", "url": "/icons/libraries",