SPECCER was originally created to simplify documenting components in a design system, but it can be used to annotate or highlight any HTML element on a webpage. If you need to draw attention to elements, SPECCER is your tool!
- @phun-ky/speccer
npm i --save @phun-ky/speccer
Types can be found in @phun-ky/speccer/dist/speccer.d.ts.
Either import and run the required functions:
import '@phun-ky/speccer/dist/speccer.min.css';
import speccer from '@phun-ky/speccer';
// do stuff
speccer();If you're importing SPECCER instead of with a script tag, you can use the following approach to apply lazy loading:
import { pin } from "https://esm.sh/@phun-ky/speccer";
const { pinElements } = pin;
/**
* Callback function for IntersectionObserver
* @param {IntersectionObserverEntry[]} entries - Array of entries being observed
* @param {IntersectionObserver} observer - The IntersectionObserver instance
* @returns {Promise<void>} Promise that resolves when element dissection is complete
*/
const intersectionCallback: IntersectionObserverCallback = async (entries, observer) => {
entries.forEach(async (entry) => {
if (entry.intersectionRatio > 0) {
await pinElements(entry.target);
observer.unobserve(entry.target);
}
});
};
// Creating IntersectionObserver instance with the callback
const pinElementObserver = new IntersectionObserver(intersectionCallback);
/**
* Function to observe elements using IntersectionObserver
* @param {Element} el - The element to be observed
*/
const observeElement = (el: Element): void => {
pinElementObserver.observe(el);
};
// Observing elements with the specified data attribute
document.querySelectorAll('[data-speccer="pin-area"]').forEach((el) => {
observeElement(el);
});Or place these script and link tags in your web page:
<link rel="stylesheet" href="../path/to/speccer.min.css" />
<script src="../path/to/speccer.js"></script>Or with a CDN:
<link
rel="stylesheet"
href="https://unpkg.com/@phun-ky/speccer/dist/speccer.min.css"
/>
<script src="https://unpkg.com/@phun-ky/speccer/dist/speccer.js"></script>And then follow the steps below to display the specifications you want :)
If you want to control SPECCER a bit more, you have some options. Apply one of these attributes to the script element for different types of initialization:
<script src="../speccer.js" data-<manual|instant|dom|lazy></script>Or with a CDN:
<script src="https://unpkg.com/@phun-ky/speccer/dist/speccer.js" data-<manual|instant|dom|lazy></script>| Tag | Description |
|---|---|
data-manual |
Makes window.speccer() available to be used when you feel like it |
data-instant |
fires off speccer() right away |
data-dom |
Waits for DOMContentLoaded |
data-lazy |
Lazy loads speccer() per specced element |
If no attribute is applied, it will default to data-dom, as in, it will initialize when DOMContentLoaded is fired.
If you use React, you can use an effect like this:
import React, { useEffect } from 'react';
import PropTypes from 'prop-types';
import debounce from './lib/debounce';
import '@phun-ky/speccer/dist/speccer.min.css';
const Component = () => {
let speccerEventFunc;
useEffect(async () => {
const { default: speccer } = await import('@phun-ky/speccer');
speccer();
speccerEventFunc = debounce(function () {
speccer();
}, 300);
window.addEventListener('resize', speccerEventFunc);
return () => {
window.removeEventListener('resize', speccerEventFunc);
};
}, []);
return <div />;
};
export default Component;
Use the following attribute to display element padding and margin:
<div data-speccer="spacing [padding|margin] [bound]" class="…"></div>This will display the element and all of it's children padding and margin, unless you specify padding and margin
This option binds the speccer elements to the bounds of the element container.
<div data-speccer="spacing bound" class="…"></div>
Display dimensions with:
<div
data-speccer="measure [height left|right] | [width top|bottom]"
class="…"
></div>Where height and width comes with placement flags. Default for height is left, default for width is top.
Use a slim style:
<div data-speccer="measure slim height left" class="…"></div>This will give a slimmer look and feel.
Use a subtle style for the slim option, uses a dashed line instead of a solid line:
<div data-speccer="measure slim height left subtle" class="…"></div>This will give a dashed border.
In your component examples, use the following attribute. Remember to use the data-speccer="pin-area"-attribute on a parent element to scope the marking.
<div data-speccer="pin-area">
<div
data-speccer="pin [bracket [curly] |enclose] [left|right|top|bottom]"
class="…"
></div>
</div>This will place a pin to the outline of the element. Default is top.
<div data-speccer="pin-area">
<div data-speccer="pin" class="…"></div>
</div>
<div data-speccer="pin-area">
<div data-speccer="pin enclose" class="…"></div>
</div>
<div data-speccer="pin-area">
<div data-speccer="pin enclose" class="…"></div>
</div>
You can also align the pins to the parent container.
<div data-speccer="pin-area">
<div data-speccer="pin parent [left|right|top|bottom]" class="…"></div>
</div>Note
Only works with pin [left|right|top|bottom], and not with enclose, bracket or curly!
The lines from the element to the pin is drawn with a svg path and circle, so remember to add the following svg into your document:
<svg
class="ph-speccer"
viewBox="0 0"
id="ph-speccer-svg"
xmlns="http://www.w3.org/2000/svg"
>
<path
class="ph-speccer path original"
id="ph-speccer-path"
fill="none"
stroke-width="1"
stroke="currentColor"
/>
</svg>
If you want text-in-place pinning feature, instead of referencing the pins, you can use the text feature:
<input
type="text"
…
data-speccer="pin left text"
data-speccer-title="Static text"
data-speccer-description="Document size [xx] by [yy][units]"
…
/>
You can use custom literals by assigned a global variable with the literals you want:
window.SPECCER_LITERALS = [
'あ',
'い',
'う',
'え',
'お',
'か',
'き',
'く',
…
];Or with a data attribute on the data-speccer="pin-area"-element:
<div data-speccer="pin-area" data-speccer-literals="ऄ|अआइईउऊऋऌऍऎएऐऑऒओऔकखगघङच">
…
</div>Tip
Try it out with emoticons!
window.SPECCER_LITERALS = [
'🥰',
…
];
You can also give a more subtle touch to the anatomy elements.
<div data-speccer="pin-area">
<div data-speccer="pin top subtle" class="…"></div>
</div>This will give a dashed border, and a more subtle pin style.
You can use curly brackets with the curly tag in data-speccer along side pin bracket to provide a more sleek style.
Note
Only works with pin bracket
The curly brackets are made with SVG paths, and it is required to have the following snippet on your page for it to render:
<svg
class="ph-speccer"
viewBox="0 0"
id="ph-speccer-svg"
xmlns="http://www.w3.org/2000/svg"
>
<path
class="ph-speccer path original"
id="ph-speccer-path"
fill="none"
stroke-width="1"
stroke="currentColor"
/>
</svg>from v9.5 you can utilize the pin feature to annotate or highlight the anatomy of an element programaticaly. Here is an example with a click event.
Kazam_screencast_00002.webm
Display typography details:
<p data-speccer="typography [left|right|top|bottom]" class="…">Some text</p>This will place a box to display typography information. Default is left.
Note
getComputedStyles are used to get the computed values, so for example, a line-height set to 1.5 will be presented in pixels, like 96px if the font-size is set to 64px.
If you want to produce a box that uses pre and code tags with support for syntax highlighting (PrismJS compatible), add syntax to the data-speccer="typography" attribute.
<p data-speccer="typography syntax right" class="…">Some text</p>You can then override the colors, based on these variables:
.ph-speccer.speccer.typography.syntax {
--ph-speccer-color-code-color-1: #737373;
--ph-speccer-color-code-color-2: #ff3aa8;
--ph-speccer-color-code-color-3: #38383d;
--ph-speccer-color-code-color-4: #ff3aa8;
--ph-speccer-color-code-color-5: #ff3aa8;
--ph-speccer-color-code-color-6: #0074e8;
--ph-speccer-color-code-color-7: #000000;
--ph-speccer-color-code-color-8: #cd0404;
}Here is an example with these colors and overrides:
.ph-speccer.speccer.typography.syntax {
color: #8c9b9b;
background-color: #262831;
border-radius: 0.375rem;
font-size: 12px;
line-height: 1.5;
border: none;
--ph-speccer-color-code-color-1: #859ba3;
--ph-speccer-color-code-color-2: #c79500;
--ph-speccer-color-code-color-3: #2caaa0;
--ph-speccer-color-code-color-4: #469edd;
--ph-speccer-color-code-color-5: #8c9b9b;
--ph-speccer-color-code-color-6: #e4e4e7;
--ph-speccer-color-code-color-7: #262831;
--ph-speccer-color-code-color-8: #ff6666;
}
This will highlight the grid spacing in a display: grid; element.
In your component examples, use the following attribute on your grid container.
<div data-speccer="grid" …>…</div>Tip
If you only want to display rows or columns, use this syntax (default is both with grid only):
<div data-speccer="grid [rows|columns]" …>…</div>
This will mark the given elements.
In your component examples, use the following attribute.
<div data-speccer="mark" …>…</div>With SPECCER, you can also display accessibility notation, like Accessibility Bluelines or A11y Annotation Kit:
Prior art: Jeremy Elder and Stephanie Hagadorn
If you want to display tab stops, append data-speccer="a11y tabstops" as an attribute to the container you want to display the tab stops in.
If you want to display landmarks and regions, append data-speccer="a11y landmark" as an attribute to the container you want to display the landmarks and regions in.
If you want to display headings, append data-speccer="a11y headings" as an attribute to the container you want to display the headings in.
If you want to display autocomplete, append data-speccer="a11y autocomplete" as an attribute to the container you want to display the autocomplete in.
If you want to display the shortcut with keys used for elements, use data-speccer="a11y shortcut" and data-speccer-a11y-shortcut="<shortcut>" on the element that uses this shortcut:
<button
type="button"
data-speccer="a11y shortcut"
data-speccer-a11y-shortcut="ctrl + s"
>
Save
</button>
Allthough the styling works nicely with dark mode, you can use the provided CSS variables to customize the look and feel. If more control is needed, you can use CSS overrides :)
.ph-speccer.speccer {
--ph-speccer-color-artificialStrawberry: #ff3aa8;
--ph-speccer-color-venusSlipperOrchid: #db6fff;
--ph-speccer-color-superBanana: #fff76f;
--ph-speccer-color-white: #ffffff;
--ph-speccer-color-carbon: #333333;
--ph-speccer-color-red: #ff0000;
--ph-speccer-color-niuZaiSeDenim: #0074e8;
--ph-speccer-color-beautifulBlue: #1868b2;
--ph-speccer-color-fuchsiaBlue: #7e60c5;
--ph-speccer-base-color: var(--ph-speccer-color-artificialStrawberry);
--ph-speccer-spacing-color: var(--ph-speccer-base-color);
--ph-speccer-spacing-padding-color: var(--ph-speccer-color-carbon);
--ph-speccer-spacing-padding-color-background: rgb(
from var(--ph-speccer-color-venusSlipperOrchid) r g b /
var(--ph-speccer-opacity-40)
);
--ph-speccer-spacing-margin-color: var(--ph-speccer-color-red);
--ph-speccer-spacing-margin-color-background: rgb(
from var(--ph-speccer-color-superBanana) r g b /
var(--ph-speccer-opacity-40)
);
--ph-speccer-spacing-line-width: var(--ph-speccer-line-width);
--ph-speccer-typography-background-color: var(--ph-speccer-color-white);
--ph-speccer-typography-color-property: var(--ph-speccer-color-niuZaiSeDenim);
--ph-speccer-typography-color-text: var(--ph-speccer-base-color);
--ph-speccer-typography-color-value: var(--ph-speccer-base-color);
--ph-speccer-mark-background-color: rgb(
from var(--ph-speccer-base-color) r g b / var(--ph-speccer-opacity-20)
);
--ph-speccer-mark-border-color: var(--ph-speccer-base-color);
--ph-speccer-mark-border-width: 1.5px;
--ph-speccer-mark-border-style: solid;
--ph-speccer-measure-color: var(--ph-speccer-color-red);
--ph-speccer-measure-line-width: 1.5px;
--ph-speccer-measure-border-style: dotted;
--ph-speccer-measure-size: 8px;
--ph-speccer-a11y-color-background: var(--ph-speccer-color-beautifulBlue);
--ph-speccer-a11y-landmark-color-background: var(
--ph-speccer-color-fuchsiaBlue
);
--ph-speccer-color-text-light: var(--ph-speccer-color-white);
--ph-speccer-color-text-dark: var(--ph-speccer-color-carbon);
--ph-speccer-pin-color: var(--ph-speccer-base-color);
--ph-speccer-pin-size: 24px;
--ph-speccer-pin-space: 48px;
--ph-speccer-line-height: 12px;
--ph-speccer-line-width: 1.5px;
--ph-speccer-line-width-negative: -1.5px;
--ph-speccer-opacity-20: 0.2;
--ph-speccer-opacity-40: 0.4;
--ph-speccer-font-family: 'Menlo for Powerline', 'Menlo Regular for Powerline',
'DejaVu Sans Mono', Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono',
monospace;
--ph-speccer-font-size: 12px;
--ph-speccer-transition-default: all 2s cubic-bezier(0.4, 0, 0.2, 1);
}Full API documentation is available here.
// Build
$ npm run build
// Run dev
$ npm run dev
// Test
$ npm test
Want to contribute? Please read the CONTRIBUTING.md and CODE_OF_CONDUCT.md
This project is licensed under the MIT License - see the LICENSE file for details.
See the CHANGELOG.md for details on the latest updates.
See the discussions for an FAQ or to ask questions if no answer is given.
I'm an Open Source evangelist, creating stuff that does not exist yet to help get rid of secondary activities and to enhance systems already in place, be it documentation or web sites.
The sponsorship is an unique opportunity to alleviate more hours for me to maintain my projects, create new ones and contribute to the large community we're all part of :)
Support me on GitHub Sponsors.
p.s. Ukraine is still under brutal Russian invasion. A lot of Ukrainian people are hurt, without shelter and need help. You can help in various ways, for instance, directly helping refugees, spreading awareness, putting pressure on your local government or companies. You can also support Ukraine by donating e.g. to Red Cross, Ukraine humanitarian organisation or donate Ambulances for Ukraine.