Start
Get Started
Three steps: load it, add a tell, change its state. Working with a coding assistant? Skip to Build with AI and let it do these for you.
1. Load It
Three ways to load it, all the same element. Pick the one that matches how you build. Flip on the play bundle and tells glance at the pointer, dance, and doze off.
Using a bundler? Install the package and import it once, anywhere:
npm i tiny-tells
import 'tiny-tells';
The import registers the element as it runs. Types ship in the package. Need the class itself? Import it
by name with
import { TinyTell } from 'tiny-tells'.
No build step? Add the script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/tiny-tells@0.5.0/dist/tiny-tells.min.js"></script>
Copy dist/tiny-tells.min.js from the package into your site and load it like
any other module. Want to read or debug it? dist/tiny-tells.js is the same
code, unminified.
<script type="module" src="/js/tiny-tells.min.js"></script>
2. Add a Tell
Put it next to the words it describes. label="" stops screen readers from saying the state twice.
role="status" announces the words when they change. More on that.
<p>
<tiny-tell tell="dekatron" state="working" label=""></tiny-tell>
<span role="status">Syncing 3 files…</span>
</p>
3. Change Its State
Set state from your code, and change the words at the same time.
const tell = document.querySelector('tiny-tell');
const words = document.querySelector('[role="status"]');
tell.state = 'done';
words.textContent = 'Synced 3 files.';
Build with AI
Claude Code, Codex, Cursor, Copilot: any assistant that can read a URL can add Tiny Tells for you. Point it at
llms.txt, a plain-text copy of these docs written for assistants. It has the
install, the attributes, and the rules an assistant gets wrong without them (words beside every tell,
warning only when a person has to act).
Paste-In Prompt
For a one-off. Paste it into the chat:
Add Tiny Tells to this project. Read https://tinytells.dev/llms.txt first, and follow its rules for pairing each tell with status text. Ask me where it should go before adding any.
Project Rules
For every session after this one. Add this to the instructions file your assistant reads on its own. Codex,
Cursor, and Copilot read AGENTS.md. Claude Code reads CLAUDE.md, which can pull in
AGENTS.md with a line that says @AGENTS.md.
## Tiny Tells
- Before adding or changing a `<tiny-tell>`, read https://tinytells.dev/llms.txt and follow its Rules.
Agent Skill
For assistants that load skills. Install it in your project once:
npx skills add talbs/tiny-tells
It’s the same text as llms.txt, so the rules and API are there without fetching anything. Run
npx skills update after you upgrade Tiny Tells.
Manifest and Types
Installed from npm, the package carries its own description. custom-elements.json lists every
attribute, event, and CSS hook. The TypeScript types flag tell.state = 'workin' before it ships.
See Frameworks and Editors.
Use
Tells
Pick one with tell. They all say the same five things. What differs is the personality, so pick
the one that fits your product. A typo logs a warning and gets you Drones.
| Tell | tell |
Who It Is |
|---|---|---|
drones | A squad of four drones running drills, keen and prone to pile-ups. Their shadows are the floor. | |
flipdot | A 5×5 flip-disc board, like the ones on old bus signs. Every disc clacks over and wobbles before it settles. All business. | |
eyes | Two eyes on a dark visor, and the most human of the six. The eyes dart first, the head catches up, and every mood morphs into the next. | |
blot | A drop of cartoon liquid that reaches, drips, splats, and pulls itself back together, with real gravity and generous squash and stretch. | |
dekatron | A 1950s counting tube. One glow hops around a ring of ten. Precise and steady, right up until it jams. | |
lens | One calm, watchful eye behind smoky glass in a metal bezel. The iris does all the talking. |
States
Set one with state. A typo logs a warning and gets you working.
| Tell | state |
Means | Use It |
|---|---|---|---|
working | Busy and making progress. | For the whole wait, from the first step to the last. | |
done | Finished, and it worked. | Once the work is really finished, not just sent. | |
error | Failed. | Always with words beside it that say what broke. | |
warning | Stuck until a person acts. | When someone has to act on an approval, a conflict, or a sign-in, and nothing is broken. | |
idle | Nothing in progress. | For anything ready, queued, or up to date, when nobody is waiting on it. |
People mix up warning and idle. Warning means someone has to act. Idle means
nobody’s waiting. Whatever the state, put words beside it. When the change matters, put them in a
role="status" region so screen readers announce it:
<p>
<tiny-tell state="warning" label=""></tiny-tell>
<span role="status">Waiting for your approval to deploy.</span>
</p>
<p>
<tiny-tell state="idle" label=""></tiny-tell>
<span role="status">Deploy queued.</span>
</p>
In a list or table, each row’s tell keeps its state name. A region per row announces each row as it changes, so put the summary in one region:
-
report.pdf -
photo.jpg
1 of 2 uploaded.
<ul>
<li><tiny-tell state="done"></tiny-tell> report.pdf</li>
<li><tiny-tell state="working"></tiny-tell> photo.jpg</li>
</ul>
<p role="status">1 of 2 uploaded.</p>
Accessibility
A tell is a hint, never the message. The words carry the status. The tell is what you notice at a glance. Tiny Tells handles motion, contrast, forced colors, and flashing. The one thing it can’t know is what’s actually happening, so that part is yours.
Your Part
- Put words beside it, not inside the tag. A tell is never the only signal. Text inside the tag hides once the tell loads. See it.
-
Hide its name when the words already say it with
label="". It works likealt=""on a decorative image. Try it. -
If the status changes while someone’s on the page, put the words in a
role="status"region so screen readers announce it. Keep the region in the page from the start, and hide what’s inside it, not the region. A list gets one region for the summary. Run it. - If you change the colors, keep 3:1 against the surface (WCAG 1.4.11). Check yours.
- If it moves for more than five seconds, give people a pause button (WCAG 2.2.2). Copy one.
-
If you load play, put
noplayon busy lists, so only the tells you want playing do. See how.
Handled for You
-
A name. Shows up as an image named by its state, or by the
labelattribute. - Reduced motion. Holds one still pose per state, and play turns off.
- Forced colors. Draws in the system text color in Windows High Contrast mode.
- Contrast. Meets 3:1 with the built-in palette.
- Flashing. Never more than three flashes a second (WCAG 2.3.1).
- Off-screen. Stops animating while it’s scrolled out of view.
- Pausing. Holds its current frame with the
pausedattribute.
Labels
Screen readers read a tell as an image named after its state, like “Working”. Set label to be
more specific. Set label="" to hide the tell when the words beside it already say the state.
Forget it beside a live region, and the console reminds you.
label, not aria-label.
aria-label and aria-labelledby work too, and override label. Firefox
ignores them before version 119, though, so label is the safe one.
| Tell | Attribute | Screen Readers Hear |
|---|---|---|
|
|
no label |
“Working”, an image |
|
|
label="Uploading photos" |
“Uploading photos”, an image |
|
|
label="" |
Nothing. The tell is hidden. |
|
|
no label, inside a role="status" region |
“Working”, an image, then the words, on every change |
<tiny-tell></tiny-tell>
<tiny-tell label="Uploading photos"></tiny-tell>
<tiny-tell label=""></tiny-tell>
<p role="status"><tiny-tell></tiny-tell> Saving…</p>
Pausing
paused freezes a tell on its current frame. Remove it and the tell rejoins the shared beat.
Anything that moves for more than five seconds needs a way to stop it (WCAG 2.2.2). One button covers every tell on the page:
<button type="button" id="pause-tells">Pause animations</button>
<script>
let isPaused = false;
document.getElementById('pause-tells').addEventListener('click', event => {
isPaused = !isPaused;
event.currentTarget.textContent = isPaused ? 'Resume animations' : 'Pause animations';
document.querySelectorAll('tiny-tell').forEach(tell => (tell.paused = isPaused));
});
</script>
Customize
Size
Usually you don’t set one.
Follow the Text
A tell sizes itself to the text it sits in: about 1.4 times the font size, never under 20px or over 48px.
Under the hood that’s clamp(20px, 1.43em, 48px).
Syncing your files
Syncing your files
Syncing your files
<p>Syncing your files <tiny-tell></tiny-tell></p>
Pin a Size
Set --tell-size when a tell should hold one size whatever the text does (a toolbar, a table
column). It inherits, so set it on the tell or any container above it:
.toolbar { --tell-size: 1.5rem; }
Pick a Value
Any CSS length works. They’re drawn for 20 to 48px, though, and it shows outside that range:
tiny-tell { --tell-size: 2rem; }
Color
Five custom properties, one per state. Set them on :root or any container, with any CSS color,
light-dark() included. Skip one and it keeps the built-in color. The
play bundle adds a sixth for its dance.
The rule: 3:1 against the surface behind the tell. The built-in palette clears it in light and dark. Pick a palette below and the chips check it for you.
The CSS for the palette you picked:
Use Your Design System’s Colors
Point the tokens at your system’s, and declare them on the same selectors your system uses to switch theme. The names below are stand-ins:
data-theme="light"
data-theme="dark"
:root,
[data-theme] {
--tell-color-working: var(--color-accent);
--tell-color-done: var(--color-success);
--tell-color-error: var(--color-danger);
--tell-color-warning: var(--color-warning);
--tell-color-idle: var(--color-neutral);
}
var() resolves where it’s declared. Set the tokens only on :root and a dark
region still gets the light values.
Match the Text Color
color="current" drops the state colors and draws in the text color around the tell, even inside
another component’s slot. Use it on a filled button or a badge, where green on brand blue looks like a
mistake.
Default: state colors
color="current": matches the text
<tiny-tell></tiny-tell>
<tiny-tell color="current"></tiny-tell>
Match Light or Dark
Each tell has a light drawing and a dark one, and scheme picks. auto (the default)
reads the color-scheme around it. Use invert for a tell on a filled badge or button.
In a light region
autolightdarkinvertIn a dark region
autolightdarkinvert<tiny-tell scheme="auto"></tiny-tell>
<tiny-tell scheme="light"></tiny-tell>
<tiny-tell scheme="dark"></tiny-tell>
<tiny-tell scheme="invert"></tiny-tell>
Styling
Size and color cover most of it. Past that, you get two hooks. The drawing itself is one canvas, so there’s nothing inside to restyle.
- The canvas:
::part(tell). Opacity, filters, transforms. -
The state:
:state(working),:state(done), and so on. Style the things around the tell by what it’s showing. These need newer browsers. The second line below is the fallback for older ones.
tiny-tell:state(error) + .message { color: var(--danger); }
tiny-tell[state="error"] + .message { color: var(--danger); }
Matching working by attribute? Add tiny-tell:not([state]) too. A tell with no
state is working.
Default: full strength
.muted: steps back
.muted tiny-tell::part(tell) { opacity: 0.6; }
Play Bundle
The same element and API, with three extras for the person at the screen. It costs under 2.5 KB more, gzipped. The core bundle reports status and that’s it. Reach for play when the tell is part of the product’s personality.
| Extra | Happens When |
|---|---|
| Glance | a mouse pointer comes near |
| Dance | someone taps it five times quickly, or you call tell.dance() |
| Doze | an idle tell is left alone for 30 seconds. It wakes when the pointer comes back. Never on touch screens. |
-
Skip it with
noplay. The tell keeps its state animation, with no glance, tap dance, or doze. Use it where many tells sit together, like a dense table.tell.dance()still works. - Reduced motion and
pausedboth switch play off. -
Recolor the dance with
--tell-color-dance(sky blue by default). Any CSS color works,light-dark()included. It wins overcolor="current", so a tell that matches its text can still dance in color.
Core: keeps to itself
Play: looks your way
Load it in place of the core bundle:
import 'tiny-tells/play';
<script type="module" src="https://cdn.jsdelivr.net/npm/tiny-tells@0.5.0/dist/tiny-tells-play.min.js"></script>
<script type="module" src="/js/tiny-tells-play.min.js"></script>
Integrate
Frameworks and Editors
It’s a plain custom element. Anything that renders HTML renders a tell, and Svelte, Lit, and plain HTML need nothing else. React, Vue, and Angular each want one small setup step, below.
Types and Editors
-
TypeScript:
dist/tiny-tells.d.tstypes the element and exportsTinyTell,TinyTellAttributes,TellName,TellState,TellColor, andTellScheme. The play bundle’s types addTellDanceEvent,TellAfterDanceEvent, and the dance events onaddEventListener. -
Custom Elements Manifest:
dist/custom-elements.jsondescribes the element to anything that reads the format: Storybook, docs generators, coding assistants. The package’scustomElementsfield points to it, so most tools find it on their own. -
VS Code: add the custom data file to
html.customDatafor attribute autocomplete in HTML files. On the CDN or self-hosting, download the same file into your project and point the setting at it.
{
"html.customData": ["./node_modules/tiny-tells/dist/vscode.html-custom-data.json"]
}
React
React 19 works out of the box.
paused off instead of setting it to false.
React 18 writes every value as an attribute string, so paused={false} becomes
paused="false", and that still pauses.
With TypeScript, drop this in any .d.ts file so <tiny-tell> type-checks in
JSX. It works with React 18 and 19 types:
import type { DetailedHTMLProps, HTMLAttributes } from 'react';
import type { TinyTell, TinyTellAttributes } from 'tiny-tells';
declare module 'react' {
namespace JSX {
interface IntrinsicElements {
'tiny-tell': DetailedHTMLProps<HTMLAttributes<TinyTell>, TinyTell> & TinyTellAttributes;
}
}
}
Vue and Angular
Both need to be told <tiny-tell> isn’t one of their components. In Vue, pass this to the
Vue plugin in vite.config.js:
vue({
template: { compilerOptions: { isCustomElement: tag => tag === 'tiny-tell' } },
})
In Angular, add CUSTOM_ELEMENTS_SCHEMA to the component that uses it:
@Component({
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
Web Awesome
This site runs on Web Awesome, so the examples below are live. A tell
goes in a slot like anything else. Give it color="current" and it takes the component’s text
color, which is what keeps it readable on a loud button. For state colors, pick the Web Awesome preset under
Use Your Design System’s Colors.
In a button’s start slot. Click it.
<wa-button variant="brand">
<tiny-tell slot="start" tell="eyes" state="idle" color="current" label=""></tiny-tell>
Save
</wa-button>
On click: working while the save runs, then done.
const button = document.querySelector('wa-button');
const tell = button.querySelector('tiny-tell');
button.addEventListener('click', async () => {
tell.state = 'working';
await save();
tell.state = 'done';
});
In a callout’s icon slot:
<wa-callout variant="warning">
<tiny-tell slot="icon" tell="eyes" state="warning" color="current" label=""></tiny-tell>
Two copies of this file changed. Pick the one to keep.
</wa-callout>
Inline in a tag:
<wa-tag>
<tiny-tell tell="eyes" state="idle" color="current" label=""></tiny-tell>
Queued
</wa-tag>
Agent Status
An agent run fits the five states. A spinner covers
working. What it can’t show is warning: the run stopped and it’s waiting on a
person. That’s the state that costs time when nobody notices it.
Map your SDK’s status to a state, set it on the tell, and put the words in a
role="status" region. A chat reply counts as a run. A run someone stopped is your call (most apps
go back to idle).
| State | The Run Is | AI SDK | LangGraph.js | OpenAI Agents SDK | Claude Agent SDK |
|---|---|---|---|---|---|
working |
thinking or streaming | status is submitted or streaming |
invoke() hasn’t returned |
run() hasn’t settled |
query() is still yielding |
done |
finished | status is ready after a reply |
returned with no __interrupt__ |
returned with no interruptions |
a result message with subtype success |
error |
failed | status is error |
invoke() threw |
run() threw |
any other result subtype, or it threw |
warning |
waiting on a person | a tool part in approval-requested |
__interrupt__ in the result |
result.interruptions has entries |
canUseTool hasn’t returned |
idle |
not started | status is ready before any reply |
nothing started yet | nothing started yet | nothing started yet |
Set State and Words Together
The LangGraph, OpenAI, and Claude examples share this:
const tell = document.querySelector('tiny-tell');
const words = document.querySelector('[role="status"]');
const TEXT = { working: 'Thinking…', done: 'Done', error: 'Something broke', warning: 'Needs your OK', idle: 'Ready' };
const show = state => {
tell.state = state;
words.textContent = TEXT[state];
};
show() in the page, not next to the SDK.
Those SDKs usually run on a server. Call it wherever the page hears about the run: a stream, a socket, or a
poll.
AI SDK
-
readymeans two things: nothing started yet, or a reply (orstop()) just finished. This example calls it done once there’s a reply on the page. -
Approvals go back on their own with
sendAutomaticallyWhen, so done means the tool really ran.
import { useChat } from '@ai-sdk/react';
import { lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai';
const TEXT = { working: 'Thinking…', done: 'Done', error: 'Something broke', warning: 'Needs your OK', idle: 'Ready' };
const stateOf = (status, messages) => {
const parts = messages.at(-1)?.parts ?? [];
if (parts.some(p => p.state === 'approval-requested' && !p.approval?.isAutomatic)) return 'warning';
if (status === 'error') return 'error';
if (status !== 'ready') return 'working';
return messages.length ? 'done' : 'idle';
};
function RunStatus() {
const { status, messages } = useChat({
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
});
const state = stateOf(status, messages);
return (
<p>
<tiny-tell state={state} label="" /> <span role="status">{TEXT[state]}</span>
</p>
);
}
approval-requested too, with approval.isAutomatic set. Count
them and the tell shows warning when nobody needs to act.
LangGraph.js
A paused graph comes back with __interrupt__ set. Answer it with
new Command({ resume }) on the same thread and it’s working again:
show('working');
try {
const result = await graph.invoke(input, config);
show(result.__interrupt__?.length ? 'warning' : 'done');
} catch {
show('error');
}
OpenAI Agents SDK
A run that needs approval stops and fills result.interruptions. Approve or reject each one on
result.state, then run again:
import { run } from '@openai/agents';
show('working');
try {
const result = await run(agent, input);
show(result.interruptions.length ? 'warning' : 'done');
} catch {
show('error');
}
Claude Agent SDK
The run doesn’t stop for approval. It waits inside canUseTool until you answer, so the tell
switches to warning there and back when the person decides. askUser stands in for
your own approval UI:
import { query } from '@anthropic-ai/claude-agent-sdk';
const canUseTool = async (toolName, input) => {
show('warning');
const isAllowed = await askUser(toolName, input);
show('working');
return isAllowed ? { behavior: 'allow', updatedInput: input } : { behavior: 'deny', message: 'Declined' };
};
show('working');
try {
for await (const message of query({ prompt, options: { canUseTool } })) {
if (message.type === 'result') show(message.subtype === 'success' ? 'done' : 'error');
}
} catch {
show('error');
}
Testing Your App
- Test DOMs (jsdom, happy-dom): tells go inert. Attributes and properties work, nothing draws, and nothing logs, so Jest and Vitest output stays clean.
- Screenshot tests (Playwright, Puppeteer): emulate reduced motion. Every state holds one fixed pose, so screenshots match from run to run.
await page.emulateMedia({ reducedMotion: 'reduce' });
Before It Loads
Until the script runs, <tiny-tell> is an empty inline element. Then the tell appears and
shoves the words beside it over. A late tell is fine (the words already say the status). The layout shift
isn’t, and it counts against your Cumulative Layout Shift.
Hold Its Space
Load reserve.css before the script. It gives every tell the box it’ll have once it loads, so
nothing moves:
import 'tiny-tells/reserve.css';
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tiny-tells@0.5.0/dist/reserve.css">
<link rel="stylesheet" href="/css/reserve.css">
Show a Stand-In
If the script might never arrive (a blocked CDN, JavaScript off), draw something in the reserved space. The
state attribute is already on the tag, so plain CSS can follow it:
tiny-tell:not(:defined) { display: inline-grid; place-items: center; }
tiny-tell:not(:defined)::before { content: "•"; }
tiny-tell:not(:defined)[state="done"]::before { content: "✓"; }
tiny-tell:not(:defined)[state="error"]::before { content: "✕"; }
tiny-tell:not(:defined)[state="warning"]::before { content: "!"; }
Anything inside the tag shows until the element loads, then hides. With reserve.css it’s clipped
to the tell’s box, so keep it to an icon or a short word.
To wait for it from script: await customElements.whenDefined('tiny-tell').
Reference
API
Attributes and Properties
Every attribute except noplay is also a property (tell.state = 'error'). Unknown
values fall back to the default. An unknown tell or state logs a warning too.
| Attribute | Values | Default |
|---|---|---|
tell | One of the six tells Which tell to draw. How to use it. | drones |
state | One of the five states What the tell is reporting. Changing it hands off into the new state. How to use it. | working |
color | state, currentWhere the color comes from. How to use it. | state |
scheme | auto, light, dark, invertLight or dark drawing. How to use it. | auto |
label | text Accessible name. Defaults to the state. Set it to an empty string when nearby text already says the state. How to use it. | — |
paused | boolean Holds the current frame. How to use it. | — |
noplay | boolean Turns play off for this tell. It won’t glance at the pointer, dance to five taps, or doze, but it still animates its state. Set it in markup or with toggleAttribute('noplay'). How to use it. | — |
CSS Custom Properties
All of them inherit. Size and Color show them in use.
| Property | Default | Does |
|---|---|---|
--tell-size | clamp(20px, 1.43em, 48px) | Width and height. Tuned for 20 to 48px. |
--tell-color-working | — | Working color. Any CSS color, including light-dark(). |
--tell-color-done | — | Done color. Any CSS color, including light-dark(). |
--tell-color-error | — | Error color. Any CSS color, including light-dark(). |
--tell-color-warning | — | Warning color. Any CSS color, including light-dark(). |
--tell-color-idle | — | Idle color. Any CSS color, including light-dark(). |
--tell-color-dance | — | Dance color. Any CSS color, including light-dark(). Unlike the state colors, it applies even with color="current". |
CSS Parts
| Part | Is |
|---|---|
tell | The canvas. |
Custom States
These need newer browsers than the rest. Styling has the fallback.
| Selector | Matches When the Tell Is |
|---|---|
:state(working) | Busy and making progress. |
:state(done) | Finished, and it worked. |
:state(error) | Failed. |
:state(warning) | Stuck until a person acts. |
:state(idle) | Nothing in progress. |
Events
The core fires no events. It only shows the state you set, so there’s nothing new to report. The play bundle fires two around a dance (dozing fires none, since the state stays idle). Both bubble and cross shadow roots, so listen on the tell or anywhere above it.
| Event | Cancelable | Fires |
|---|---|---|
tell-dance | Yes | Fires before a tell dances. Call preventDefault() to keep it still. |
tell-after-dance | No | Fires when a dance ends, or when a state change, a switch to another tell, or removing it cuts it short. A removed tell is off the page, so only listeners on the tell itself hear that one. |
- Length: a dance lasts two loops, about 6.4 seconds.
-
No
tell-dancewhile a tell is paused, under reduced motion, or mid-dance. -
Pausing freezes the frame but not the dance’s clock. If the time’s up when you unpause,
tell-after-dancefires right then. - A canceled dance never started, so it gets no
tell-after-dance.
Tap it five times, or press Dance.
const tell = document.querySelector('tiny-tell');
const words = document.querySelector('[role="status"]');
const holdStill = document.querySelector('#hold-still');
tell.addEventListener('tell-dance', event => {
if (holdStill.checked) event.preventDefault();
words.textContent = holdStill.checked ? 'Asked to dance, and held still.' : 'Dancing…';
});
tell.addEventListener('tell-after-dance', () => {
words.textContent = `Back to ${tell.state}.`;
});
Static Properties
| Property | Type | Does |
|---|---|---|
TinyTell.version | string | The version that’s loaded. |
TinyTell.timeScale | number | Experimental. Multiplies every tell’s clock: 1 is normal, 0.5 is half speed, 2 is double. 0, a negative, or anything that isn’t a finite number stops them. |
Methods
| Method | Returns | Does |
|---|---|---|
dance() | boolean | Dances once, same as five quick taps. Works on a noplay tell too. Returns false when it can’t: paused, reduced motion, already dancing, off the page, or tell-dance canceled. |
Browser Support
These versions and later. That covers every browser in Baseline’s Widely available set.
Chrome 111 Firefox 113 Safari 16.4
Two features need newer browsers:
| Feature | Chrome | Firefox | Safari | In Older Browsers |
|---|---|---|---|---|
:state() selectors |
125 | 126 | 17.4 | Match the state attribute instead. |
scheme="auto" |
123 | 120 | 17.5 | Follows the system’s light or dark setting, not the container’s color-scheme. |
How It Works
A tell is animated like a character, not swapped like an icon. All six follow the same few rules, and the demos below are running them live.
One Beat, One Clock
Everything runs on a 0.8s beat. A loop is four beats (idle takes six). Every tell on the page shares one clock, so a row of them stays in time, and each lands its biggest move on the beat.
Handoffs
Change the state and the tell doesn’t cut to the new loop. It springs from wherever it is, keeping its momentum, so even a switch halfway through a move looks intended. A sprite sheet or a GIF would have to cut.
Cut: starts the new loop cold
Handoff: springs from where it is
Small on Purpose
Tells drop detail as they shrink, so each still reads at 20px. At 32px and under, Eyes loses its glow and Dekatron’s ten cathodes merge into one ring.
Drawing
Each tell is one canvas at your screen’s full resolution, and off-screen tells stop drawing. On a recent laptop, 100 on screen run above 60 fps. On a CPU four times slower, they run at about 40. Try yours:
Tested
Every change is tested in Chromium, Firefox, and WebKit, and every tell has to pass the same checks:
- stay inside its live area
- loop without a seam
- never flash more than three times a second
- draw in system colors under forced colors
Project
License
MIT. Use it in anything, commercial work included. The license file has the full text.
Versions
Pre-1.0. It’s tested, but names and defaults can still change, so pin a version. Fixes only go to the latest
release. Every release is in the
changelog, and
TinyTell.version tells you which one you’ve got.
Contributing
Bugs go in an issue: the browser, the tell, the state, what you saw. A screen recording helps a lot. For anything bigger, open an issue before the pull request so we agree on it first. New tells aren’t open yet, but fork away. Security problems go through GitHub’s private report, not a public issue. The rest is in CONTRIBUTING.md.
Stats
The site counts visits with Umami, plus which tell you pick, which install tab
you open, and which palette you try. There are no cookies, and nothing in the totals identifies you. To leave
yourself out, open ?stats=off once in each browser.
?stats=on puts you back.
Funsies
The tells are off the clock here. None of this teaches anything.
Dance Party
The whole cast dances, a sixth of a beat apart.Tap a beat