Blog Awesome

Random Content, On Purpose

2026-09-22T14:00:00Z

We built ten small demos with one Web Awesome component and a lot of dumb greeting copy. Some of them we'd ship tomorrow. A couple we'd argue about first.

<wa-random-content> is one of the smaller components in Web Awesome, and one of our favorites. You give it some children, it shows one at random. That's the whole thing. No script, no array of strings hiding in your component logic.

<wa-random-content>
  <p>Nice work.</p>
  <p>That's the one.</p>
  <p>Look at you go.</p>
</wa-random-content>

We kept wanting to use it everywhere, which is the wrong instinct. So before the list, the one rule we landed on: only randomize stuff that can change without changing what it means. A greeting can say something different every morning. A status line can't. The task count, the button labels, the numbers, all of that stays put.

Here are the ten we built.

Greetings

Every app we've ever used says "Welcome back." Every time. Forever. It takes about five minutes to create, which is kind of the point.

See the Pen Web Awesome's Random Content: Greetings by Web Awesome (@webawesome) on CodePen.

Look at what doesn't move: the "3 unexplained cases" line under the greeting. Randomize the hello, not the number. We'll keep saying that.

Empty States

A brand new user lands on an empty project list and has no idea what to do. Give them a nudge that's a little different each time.

See the Pen Web Awesome's Random Content: Empty States by Web Awesome (@webawesome) on CodePen.

The suggestion rotates, but the buttons don't, because if someone hits back and the button they clicked is gone, that's a bug as far as they're concerned. So the rotation only touches the text.

Success Confirmations

Somebody just finished something. "Saved!" is fine. It's also a missed chance to be a little fun.

See the Pen Web Awesome's Random Content: Success Confirmations by Web Awesome (@webawesome) on CodePen.

The celebration goes above the real status line, not instead of it. It gets to be playful because nobody needs it for anything.

Loading Messages

This is the one we'd push for hardest. Long tasks have to show something while they run, and that's dead air. Might as well put some personality in it.

See the Pen Web Awesome's Random Content: Loading Messages by Web Awesome (@webawesome) on CodePen.

One thing we were careful about here. The jokes are aria-hidden, and there's a separate status element that says "Generating your report. This may take a moment." A screen reader hears that once and moves on, instead of getting a new joke read out every few seconds. That would be awful.

Rotating Artwork

Any place with one decorative image (sign-up page, 404, the hero on a long article) can rotate through a few instead. Same page, slightly different look each visit. Small thing. People notice.

In our pen each image carries a color name, and the card border and button pick it up. So the whole panel shifts with the image, not just the picture.

See the Pen Web Awesome's Random Content: Rotating Artwork by Web Awesome (@webawesome) on CodePen.

Two gotchas. mode="sequence" loads the first image first, which avoids a flash on initial render. And the images you can't see still download unless you put loading="lazy" on them. Lazy loading means a brief blank the first time each one shows up, in exchange for not downloading five images to display one. We'd take that trade.

Logo Spotlight

Every marketing site has a customer logo strip. There are always more logos than fit, so somebody picks a permanent six, and the other twenty never get seen by anyone.

items="6" pulls six from the full set. autoplay swaps them every few seconds. Everybody gets some airtime.

This is one of the two we'd argue about. Not because the component is wrong for it, but because autoplay comes with homework most teams skip.

See the Pen Web Awesome's Random Content: Logo Spotlight by Web Awesome (@webawesome) on CodePen.

If you use autoplay, put a visible pause button next to it. The component already pauses on hover and focus, but the logos themselves aren't focusable, so a keyboard user has nothing to land on. We also hid the rotating logos from screen readers and listed the full client set as plain text, so assistive tech gets every name at once instead of six at a time.

Next Reads

Same trick, different content. Show a few articles from a bigger pool at the bottom of every post.

See the Pen Web Awesome's Random Content: Next Reads + Links by Web Awesome (@webawesome) on CodePen.

Honest take: if your CMS already recommends posts by tag or popularity, use that. It's smarter than random. But random beats the hand-picked "related posts" list somebody made a year ago and never touched again. We've all got one of those.

Grids

Up to here it's been one <wa-random-content> per example. Nothing says you can't run forty.

This is the other one we'd argue about. It's a narrow case. But it shows something the single examples don't, so it stayed.

An asset library waiting on thumbnails is a wall of the same placeholder. Give each tile its own random content and the wall starts looking like actual items.

See the Pen Web Awesome's Random Content: Grids by Web Awesome (@webawesome) on CodePen.

One catch. Each tile picks on its own, so two neighbors can land on the same option. With a big pool that reads as coincidence. With a small pool it reads as a bug. Give it enough options that it doesn't happen much.

Name Generator

Everything above randomizes on its own. The user never asked. This one flips it: the randomness is the feature.

Naming things is hard, so people skip it during onboarding and you end up with "Untitled Project (4)". A generate button beats a blank field.

See the Pen Web Awesome's Random Content: Name Generator by Web Awesome (@webawesome) on CodePen.

The trick is where the randomizer lives: inside one stable button. Same rule as the greeting: the name changes, the button doesn't.

Which brings up something to watch for. If the rotating content has buttons or links inside it, a shuffle can yank focus somewhere unexpected. Keep the shuffle control outside the rotating area, and skip auto-rotation entirely when there's anything interactive in the pool.

Surprise Me

Point a few of them at the same button. Our pen builds a character: one <wa-random-content> picks a class, one picks what they're carrying, one picks a quirk. Six options each. That's 216 characters from eighteen lines of copy, and every line was written by a person.

That's the part we like. The pool is small enough to write and edit by hand, and the output is big enough that nobody sees the bottom of it. mode="unique" on each one means you won't get the same Necromancer twice in a row.

See the Pen Web Awesome's Random Content: Surprise Me by Web Awesome (@webawesome) on CodePen.

Start With One

<wa-random-content> ships with Web Awesome Core. Pick one spot. A greeting is the easiest, and nobody will complain if it's bad.

View Random Content Docs

Good News: Your AI Assistant Already Knows Your Icon Kit

2026-09-11T19:48:30Z

I know…

Your coding agent can spin up a component, write the copy, and wire up your API call without breaking a sweat. But ask it to drop in the right icon, and things get janky fast. Maybe it guesses at a class name, or suggests an icon that’s not even in your Kit. Or, maybe it just taps out and tells you to go find one yourself. (Thanks?) Now there’s no more guessing. No more hallucinating.

That’s the one place this kind of workflow used to break. But no more!

Font Awesome now has real, authenticated tools built for agents. Not just a search box they can scrape. No more scraping. Whatever you’re using, from Claude Code and Cursor to Copilot, Windsurf, or (if you’re feeling nostalgic) Clippy, your agent can ask Font Awesome directly (we gave it a line to call us on) get an answer based on your actual account instead of a best guess from training data, and act on it. It’s not making new icons. It’s fetching the ones you already have access to, correctly, the first time. (Thanks, Clippy. You’re the best.)

Here’s how it’s built, from the ground up, and what each layer means for you.

It Starts With the API

Font Awesome’s GraphQL API now provides a lot more about your icons and your account than it used to. Your agent can finally know what you know about what icons your account has access to, and which icons are available in each Kit’s subset. And because GraphQL APIs are self-documenting, so you can just point an agent at api.fontawesome.com and it works out on its own how to pull icon families, styles, and releases: whatever it needs, no hand-crafted query docs required.

A lot of metadata about Font Awesome icons, like which icons are available in which styles for any given release, are publicly available from the API—no login required.

Anything tied to your account (your Kits, your custom icons) needs an access token. That’s where the CLI comes in.

Docs: GraphQL API

The fa CLI Wraps It All Up

The fa CLI is a convenient wrapper around that API, providing subcommands for common queries. It also handles authorization for any queries that access your Kits. The CLI is handy all by itself: every command returns clean JSON, which makes it a natural fit for build scripts. When used with your AI agent, it levels up the agent’s ability to work with your icons from your Kits within your projects.

fa login

Once you’re logged in, a few things come free:

Kit-aware search

Scope a search to a Kit token, and you only get icons that are actually in that Kit’s subset, custom icons included.

fa search --kit-token 8812e4e21d --query 'coffee'

You can search your Kit’s custom icons too:

fa search --kit-token 8812e4e21d --query 'coffee' --custom

SVG data and self-hosting

Pull real SVG data for official or custom icons, or download and unzip a full Kit for self-hosting. No manual download, no hunting for the right zip file.

fa kits --kit-token 8812e4e21d --download web --unzip --output kit

Want to hand-craft your own GraphQL query instead of using a built-in command? The CLI can run it for you, using your logged-in credentials, stored in your OS keychain, on supported platforms. So your agent can access your account, without handing it a plaintext token.

Docs: fa CLI

Agent Tools Pick Up From There

Font Awesome’s official Skills (/setup-fa, /suggest-icon, /add-icon, and /fa-help) install straight into your coding agent and work across Claude Code, Cursor, GitHub Copilot, Windsurf, and more. Four commands. Zero context-switching.

Install them:

npx skills add FortAwesome/fontawesome-agent-tools

Then just ask. No docs tab, no copy-pasting a class name from a search result:

/add-icon add a shopping cart icon in the Regular style to the checkout button in src/components/Header.tsx

Here’s the peanut-butter-and-jelly part: Agent Tools automatically look for fa in your PATH. If it’s there, and you’re logged in, your agent instantly inherits everything the CLI can do: Kit-subset search, your custom icons, self-hosting setup, all of it. The two are built separately, but designed to work together.

Docs: AI Agent Tools

Try It

Install the CLI. Install the agent tools. Log in once. Then ask your agent for an icon. It already knows where to look.

Get Your Agent Kit-Ready

Your Design System Should Style Your Words, Too

2026-09-08T14:00:00Z

Most design systems stop where the article starts. Web Awesome keeps going: one class styles a whole block of content, a type scale is there when you need to place text by hand, and CSS @scope keeps all of it out of your components.

Nearly every product has a blog. Most have docs and a changelog too. And somehow every team ends up styling that content from scratch, with a typography stylesheet somebody wrote two years ago and nobody wants to open. We've written that stylesheet. More than once.

It exists because most design systems stop at components. Buttons, cards, inputs, all covered. Then a Markdown file shows up and you're on your own.

We didn't want that gap in Web Awesome, so it has three things for flowing text. wa-prose styles a whole block of content at once. A type scale you can apply by hand anywhere. And a few text utilities for alignment and casing. That's enough for a blog post or a docs page without a typography stylesheet.

The One-Class Route with Prose

Put wa-prose on the wrapper and everything inside picks up spacing, sizing, and rhythm from your theme.

<div class="wa-prose">
	<h1>Release Notes: v3.2</h1>
	<p>
		This release includes improvements to form validation, a new color picker
		component, and performance fixes across the board.
	</p>
	<h2>What's New</h2>
	<ul>
		<li>Color picker with alpha channel support</li>
		<li>Form validation messages now animate in</li>
	</ul>
	<blockquote>
		<p>
			"The best component library update is the one you don't have to migrate."
			— nobody, but it should be everyone
		</p>
	</blockquote>
	<pre><code>npm install @aspect/core@3.2</code></pre>
</div>

That's it. Headings land on the scale, paragraphs get a readable line height, lists indent the same way every time. Blockquotes get a left border. Code blocks get spacing (the colors and fonts come from Native Styles, Web Awesome's base layer for standard HTML elements). All of it hangs off one token, --wa-space-scale, so if you swap themes the prose follows.

The whole point is that you don't think about it. CMS output, rendered Markdown, hand-written HTML. Drop it in and it reads fine. No class on every element.

See it in Action: Holodeck Incident 47225.7 Entry

A Star Trek captain's log with one wa-prose class on the wrapper and nothing else. Headings, lists, blockquotes, a table, figures, a code block. Zero interior classes. Prose makes it so.

See the Pen Web Awesome's Word Styling: Prose Example by Web Awesome (@webawesome) on CodePen.

Prose That Stays in Its Lane

Styling everything inside a container only works if it really is only inside. The moment your article's h2 styles land on a card you embedded mid-post, you're writing overrides again. Different file, same problem.

wa-prose is built on CSS @scope. Styles flow down from a root and stop at a boundary you set. So you can drop a component into the middle of an article and its headings stay the component's.

<div class="wa-prose">
	<h2>This heading gets prose styles</h2>
	<p>So does this paragraph.</p>

	<div class="wa-not-prose">
		<!-- Everything in here is untouched by prose styles -->
		<wa-card>
			<h2>This heading is the card's business</h2>
		</wa-card>
	</div>

	<p>Back to prose styles here.</p>
</div>

One class opts in, one opts out. No specificity fights, no !important. This is what lets wa-prose be aggressive about headings and tables in the first place. Styles that opinionated without an exit would be a liability.

Picking Sizes by Hand

wa-prose is for when you control the container. A lot of text doesn't live in one. A hero headline. A card title. The caption under a product shot. Those want the same scale without the whole prose treatment.

That's what the standalone type classes are for. Three families. Each comes bare (style, no forced size) or with a size from 3xs to 5xl, and all three share the same range, so you're never juggling two scales.

Headings

wa-heading for the default treatment, or wa-heading-3xs through wa-heading-5xl for a specific size.

<!-- Hero headline: not inside wa-prose, but on the same scale -->
<h1 class="wa-heading-4xl">
	Build with components.
	<br />
	Ship real products.
</h1>

<!-- Card title: just needs heading treatment, default size -->
<h3 class="wa-heading">Latest from the blog</h3>

Body

wa-body for body copy, sized variants for when the default is wrong.

<!-- Sidebar description: slightly smaller than default body -->
<p class="wa-body-s">
	Updated weekly with framework guides, release notes, and community highlights.
</p>

Captions

wa-caption for the small stuff: image credits, metadata, timestamps.

<!-- Image caption -->
<figcaption class="wa-caption">
	Fig 3. Component rendering benchmark: Lit vs React vs Svelte
</figcaption>

<!-- Metadata line -->
<span class="wa-caption">Published Mar 14, 2025 · 8 min read</span>

This isn't a second system. wa-prose and the manual classes read the same tokens, so a wa-heading-2xl on a card and an <h2> inside a prose block come out identical. We care about that more than it probably sounds like. Two scales that almost match is how a site ends up with nine slightly different heading sizes.

See it in Action: Ratatouille Was Right Article

A food essay. The body is wa-prose, nothing around it is. The eyebrow, the metadata line, the author card, the footnotes, the suggestion cards: all placed by hand on the same scale.

See the Pen Web Awesome's Word Styling: Type Sizing Example by Web Awesome (@webawesome) on CodePen.

Nudging Alignment and Case

The type classes set the size. The text utilities do the two other things you keep needing: alignment and casing. They stack on wa-prose or the manual classes, so a centered pull quote or an uppercase eyebrow doesn't need a CSS file.

Alignment

wa-text-start, wa-text-center, wa-text-end, wa-text-justify.

Logical properties (start/end, not left/right), so they flip in RTL without you doing anything.

<!-- Centered pull quote -->
<blockquote class="wa-text-center wa-heading-l">
	Design systems should have opinions about typography. Most don't.
</blockquote>

<!-- Justified body copy for a print-style article (use sparingly in narrow columns) -->
<div class="wa-prose wa-text-justify">...</div>

That second one works because wa-prose never sets text-align. That's on purpose. Put both classes on the same element and they get along.

Casing

wa-text-uppercase, wa-text-lowercase, wa-text-capitalize.

<!-- Eyebrow label above a section -->
<span class="wa-caption wa-text-uppercase">Case Study</span>

<!-- Normalize user-entered headings -->
<h2 class="wa-heading-xl wa-text-capitalize"></h2>

See it in Action: Thneed Changelog

A made-up product changelog with no wa-prose at all. Every piece of text is placed by hand: wa-heading-4xl for the title, wa-caption wa-text-uppercase for the category labels, wa-body-s for the entries. More work than the prose route, and the right call for a page that's mostly small labeled chunks instead of flowing text.

See the Pen Web Awesome's Word Styling: Text Utilities Example by Web Awesome (@webawesome) on CodePen.

Get Started

Check your <head> before anything else. Everything in this post lives in utilities.css, and the styling underneath prose comes from native.css. The install docs call native.css optional. For prose it isn't, and it's an easy thing to miss. Without it, wa-prose gets you spacing and sizes but no colors, fonts, or borders on the elements themselves, and the page looks half-finished.

<!-- Required: default theme + autoloader -->
<link
	rel="stylesheet"
	href="https://ka-f.webawesome.com/webawesome@3.12.0/styles/themes/default.css"
/>
<script
	type="module"
	src="https://ka-f.webawesome.com/webawesome@3.12.0/webawesome.loader.js"
></script>

<!-- Utility classes: wa-prose, the type scale, the text utilities -->
<link
	rel="stylesheet"
	href="https://ka-f.webawesome.com/webawesome@3.12.0/styles/utilities.css"
/>

<!-- Native Styles: color, fonts, and borders for the elements inside your prose -->
<link
	rel="stylesheet"
	href="https://ka-f.webawesome.com/webawesome@3.12.0/styles/native.css"
/>

Want one line? styles/webawesome.css pulls in all three.

Then put wa-prose on your content container and see how far it gets you. Our bet is most of the way. When you need to step outside it (a hero heading, a caption), reach for the type scale classes.

Dig Into the Docs

Prose Docs Text Utilities Docs Typography Tokens

One thing Web Awesome doesn't do: syntax highlighting. Bring your own Prism, Shiki, or highlight.js.

The Art of Iconography and How to Future-Proof Your Design System [Part IV]

2026-08-27T13:18:00Z

Icons may look like the smallest pieces of a design system, but they do some of the heaviest lifting. A well-built icon library communicates faster than words, scales across every surface, and — when done right — becomes one of the most recognizable parts of your brand. (We might be a little biased on this one.) Here’s how to get them right.

The Role of Icons in Visual Identity

Icons are powerful tools in visual design. They enhance user understanding and navigation while reinforcing your brand’s values and aesthetics.

Icons help make designs better in many ways. When used intentionally, they quickly show ideas without using words, reducing cognitive load to make your content easier to understand. And since icons don’t take up much space on screens, they help designs look cleaner and more interesting.

Icons also help people find their way around websites or apps by giving clear hints about where to go. Finally, people from different countries often understand these small pictures even if they don’t speak the same language, making icons great for talking to people all over the world.

Build Your Icon Catalog

A well-curated icon library is key. Select icons that are versatile and scalable, ensuring they fit seamlessly into various contexts without losing their impact.

Building an icon catalog involves several important steps.

Define icon categories (e.g., actions, objects, navigation)
Choose between custom and standard icons
Establish icon grid and sizing guidelines
Create or select a core set of frequently used icons
Develop a system for naming and organizing icons
Plan out a system for version control for your icon library

Iconography Best Practices

Consistency in icon design is crucial. Maintain uniformity in style, size, and alignment to help your users learn how to read and understand your icons. Incorporate icons into your design system thoughtfully to enhance usability without overwhelming the user.

When it comes to iconography best practices, there are several key points to consider.

Keep consistent line weights and corner radii
Make sure icons are recognizable at various sizes
Use icons to complement rather than replace text
Provide text labels or tooltips for clarity
Consider cultural context and potential misinterpretations
Test icon comprehension with user research

In an unexpected twist, similar to the “Von Restorff effect,” research has shown that incorporating slight imperfections or “wabi-sabi” elements in iconography can actually increase user trust and perceived authenticity of a brand. This Japanese aesthetic principle, when applied subtly to digital design, can make interfaces feel more human and relatable, challenging the notion that perfection is always the goal in visual design systems.

(Wabi-Sabi. Now that’s a great band name!)

Strategies for Implementing Your Design System

Create a Collaborative Design Culture

Work hard at creating a professional ecosystem between design and development teams that’s more Avengers assembling than Batman brooding. Integrate feedback loops early on in your projects to continuously refine and improve your design system, ensuring it evolves with your needs.

To foster better collaboration, consider implementing several strategies:

Hold regular cross-functional meetings
Share design and development tools
Run design system workshops and training sessions
Collaborate on documentation processes
Get both designers and developers involved in user testing

Tools for Design System Management

Tap into design system tools for efficient collaboration. Apply version control and maintenance strategies to keep your system up-to-date and cohesive.

Recommended tools and practices to consider:

Design tools: Figma, Sketch, Adobe XD
Version control: Git, Abstract
Documentation: Storybook, Zeroheight
Collaboration: InVision, Miro
Code management: GitHub, GitLab
Regular audits and updates to the design system

Future-Proofing Your Visual Design System

Stay ahead and adapt to tech advances by incorporating responsive design principles. Prepare for emerging design trends and technologies to ensure your design system remains relevant and effective.

Keep an eye on emerging tech such as:

Voice user interfaces (VUI)
Augmented and virtual reality (AR/VR)
Artificial intelligence and machine learning integration
Dark mode and other user preferences

Lastly, keep an eye on emerging display technologies, such as foldable screens, which may require adaptations to your design system.

Evolving with Your Brand

Your brand will evolve, and your design system should too. Regularly update and refine your visual elements to stay in tune with your brand’s growth and the ever-changing tech landscape.

Here’s some tips for keeping your design system up to date:

Check it yearly to see if it’s working well.
Ask users what they think about it regularly.
Keep an eye on what’s new in your industry and what your competitors are doing.
Make small, frequent updates instead of big changes all at once.
Try to keep things familiar for users while still making needed improvements.

Recap of Key Concepts

A well-executed visual design system is transformative. It empowers your brand, ensures consistency, and enhances user experience. By investing in a strong design system, you set your brand up for sustained success in the digital era.

Final thoughts:

A design system is a living entity that requires ongoing care and attention
It’s a powerful tool for aligning teams and streamlining workflows
The benefits of a robust design system extend far beyond aesthetics, impacting user satisfaction, brand perception, and overall business success
As technology evolves, your design system should adapt while maintaining its core principles
Remember that the ultimate goal is to create meaningful, cohesive experiences for your users

So, there you have it. Your design system isn’t merely a library full of pretty components — it’s the backbone of your brand’s digital presence. It’s your secret weapon for creating knockout user experiences and keeping your team on the same page.

But remember, you can’t just set it and forget it. Your design system needs love and attention to stay fresh and relevant. Keep an eye on what’s happening in your industry, listen to your users, and don’t be afraid to make tweaks along the way.

It’s all about your users. Every decision you make should be geared towards giving them a smooth, enjoyable experience. Building a design system isn’t for the faint of heart, but if you can stick with it and stay consistent, your brand (and your future self) will be much better off in the long run.

WA 3.12: Figma Design Kit 3.0, Dropdown Links, Plus Tooltip Fixes

2026-08-21T23:03:27Z

🎨 Figma Design Kit 3.0

The Official Figma Design Kit has hit its 3.0 version. We’ve added ten new components, closing the gap between Figma and the library:

Accordion
Checkbox Group
Date Input
Date Picker
File Input
Known Date
OTP Input
Time Input
Toast
Video

Additional variables, slots, and sizing options have been added as well. The full list of updates can be found here.

🔗 Links in <wa-dropdown-item>

<wa-dropdown-item> now accepts href, target, rel, and download, which gives it the ability to act like a real link. ⌘/Ctrl will still open the link in a new tab (except in Safari). Items with a submenu ignore href, there’s also a new link custom state.

💬 Tooltip Fixes

<wa-tooltip> now respects a canceled wa-hide event and stays open. Tooltips with trigger=”email” will no longer close on Escape.

🧰 There’s Always More

There’s also a bunch fixes, namely focus ring on <wa-switch>, <wa-select>‘s clear button click target, <wa-input> password toggle, <wa-dropdown>‘s aria-posinset/aria-setsize, <wa-data-grid> filtering and layout and more.

The full list of fixes can be found on the changelog.

How Does Web Awesome Stack Up Against Shoelace?

2026-08-17T16:37:18Z

The latest release of Shoelace shipped on March 11, 2025. It’s still on npm, it’s still two lines away from any HTML page, and it still works as well today as it did the day it went out.

It’s also the last Shoelace release there’s ever going to be.

None of that is news. We launched Web Awesome back in October, and the banner has been sitting on the Shoelace docs ever since. So I’m not here to tell you it happened. I’m here to answer the question everyone keeps asking:

Why should I switch to Web Awesome?

“Because it’s the successor” doesn’t cut it when you’ve got an app full of sl- tags and a manager asking why you want to spend a week on this.

So let’s put them side by side. Nothing breaks tomorrow if you stay put, but the case is better than most folks realize, and it’s a lot more than a rename.

What Actually Changed

Shoelace was a component library. Web Awesome is a design system.

That sounds like something a marketing page says, so let me be specific. Shoelace gave you 58 components, a set of --sl-* tokens, and a light and dark theme. Everything else was your problem: layout, typography, spacing, the styling of your plain old <table> and <h2>.

Web Awesome 3.11 gives you 70 free components plus the rest of the page. Native element styles. Layout and typography utilities. Eleven themes. Nine color palettes. A theming API that goes deeper than swapping two stylesheets.

And it’s still free and open source under the MIT license. That part was never negotiable.

What Folks (Probably) Care About the Most

There are components you couldn’t build with Shoelace without writing your own. <wa-callout> for inline messaging. <wa-popover> for anchored content that isn’t a tooltip and isn’t a dropdown. <wa-scroller> for overflow containers with real scroll affordances. Then <wa-accordion>, <wa-page>, <wa-number-input>, <wa-time-input>, <wa-zoomable-frame>, <wa-intersection-observer>, and more.

Your plain HTML gets styled, too. Web Awesome ships a native.css layer that styles real elements: headings, tables, form controls, <figcaption>, the works. If you were around for the original Shoelace in 2017, that might feel a little familiar. That project was a CSS starter kit before it was ever a component library. It took me about nine years, but the idea made it back in

You get CSS utilities, too. Layout primitives like wa-stack, wa-cluster, and wa-split. Gap, alignment, border radius, and text utilities. A wa-prose class for long-form content. Nothing resembling a build step.

Component styles live in @layer wa-component, which means your unlayered CSS wins by default. Go delete your !important declarations. I’ll wait.

Icons are Font Awesome by default instead of Bootstrap Icons, and if you have a Font Awesome Pro Kit, that works too.

There’s server-side rendering. As of 3.8, components render on the server via Declarative Shadow DOM and hydrate when your JavaScript arrives. Less layout shift, better first paint. It’s experimental, but it’s real and people are using it.

And there’s a theme called Shoelace. There’s a built-in shoelace theme and a matching shoelace color palette, so you can migrate the markup without explaining to your designer why every button looks different on Monday.

It installs the way it always has. Paste a stylesheet and a module script into your <head>, served from our own CDN, and start writing tags. Or npm install @awesome.me/webawesome and bundle it like anything else. No framework, no wrapper, no build step you weren’t already running.

Side by Side

	Shoelace 2	Web Awesome Core	Web Awesome Pro
Status	Sunset, 2.20.1, March 2025	Active, 3.10.0, June 2026	Active
License	MIT	MIT	Commercial, alongside the MIT core
Components	58	66	Everything free, plus the list below
Icons	Bootstrap Icons	Font Awesome Free	Font Awesome Pro via Kit
Themes	Light + dark	Default, Awesome, Shoelace	8 more (Active, Brutalist, Glossy, Matter, Mellow, Playful, Premium, Tailspin)
Color palettes	1	3	9
Native element styles	–	✅	✅
CSS utilities	–	✅	✅
Cascade layers	–	✅	✅
Server-side rendering	–	✅	✅
Theme Builder	–	–	✅
Pattern library	–	–	✅
Hosted projects + CDN	–	–	✅
Figma design kit	–	–	✅
Support	Community	Community + us	Priority support
Price	Free	Free	Commercial license

Pro components, for the record: <wa-combobox>, <wa-file-input>, <wa-date-picker>, <wa-date-input>, <wa-video>, <wa-video-playlist>, <wa-sparkline>, and the Chart.js-backed chart family (bar, line, pie, doughnut, bubble, radar, scatter, and polar area). A data grid is on the way.

A Word About Pro

I’d rather you hear this from me than figure it out halfway through a migration.

Web Awesome Pro exists so Web Awesome Core can keep existing. Every subscription pays for the bug fixes and the new components that everyone gets, free users included. Pro just moves you to the front of the line when you need a hand. Over 7,000 people backed the Kickstarter to make that model work, and I’m still a bit stunned by it.

Almost none of your migration touches Pro. The components you built your Shoelace app with are in Core, and that’s where they’re staying. The one place Pro comes up is if you had a second library bolted onto Shoelace for charts, comboboxes, or the like. Those live in Pro now, and moving to a first-party version is optional, not required.

How Hard Is This, Really?

Less hard than you’re expecting.

Most components migrate on a sl- to wa- rename and nothing else, which covers roughly two thirds of the library. Tokens go from --sl-* to --wa-*. variant="primary" becomes variant="brand". The outline and filled booleans became appearance="outlined"and appearance="filled". Slots named prefix and suffix are now start and end. help-text is now hint.

A handful of things changed shape rather than name. <sl-menu> became <wa-dropdown>, <sl-range> became <wa-slider>, <sl-image-comparer> became <wa-comparison>, and <sl-visually-hidden> is now a wa-visually-hidden utility class you can put on anything.

The parts that bite quietly are event listener strings, ::part() selectors, and icon names. None of those throw an error. They just stop doing what you expected. Color scales also inverted, so --sl-color-primary-600 doesn’t map to the number you’d guess.

All of it is written down in the migration guide, along with a checklist you can work through file by file. The guide also includes a prompt you can hand to a coding agent, and it’ll do most of the mechanical work for you. I was skeptical about including that. Then I watched it migrate a real project in an afternoon.

Should You Migrate?

If your Shoelace app is stable and shipped and you’re not touching it, no, you don’t need to do anything this week. It’ll keep working.

But there won’t be another Shoelace release. No new components, no fixes, no answers on the issue tracker. Every hour of work is going into Web Awesome now. If you’re actively building on Shoelace, every new feature you ship is more code you’ll eventually have to migrate. The sooner you switch, the less of it there is.

Start with the migration guide. Pick one page. Rename one prefix. It’s usually much easier than it sounds.

Thank You

More than a year after the last release, Shoelace is still serving over two million requests a month on jsDelivr alone. That’s all of you, still building things. Every issue, every PR, every “hey, this is broken” in Discord got the project further than I could have taken it alone, and Web Awesome is that same project with more people and more hours behind it.

Come see what we’ve built. And keep building awesome stuff!

How to Build and Style Your Visual Design System [Part III]

2026-08-13T20:41:46Z

If Part 1 was the pitch and Part 2 was the parts list, this is your build guide. We’re getting hands-on — auditing what you’ve got, defining what you need, and laying the groundwork for a system that actually scales.

Conduct a Visual Audit

First, start with a visual audit. Assess your current design elements to see what’s working, what’s not, and where there’s room for improvement. This step is crucial for aligning your visuals with your brand’s goals.

To check your company’s visual style, follow these steps:

First, make a list of all the pictures, colors, and designs you use. This helps you see what you have.
Then, look at how these elements appear on different devices so you can spot differences. Figure out what looks good and what needs work in your brand’s style. Ask for opinions from non-design folks in your company to hear different views. Look at what other companies in your field are doing to see how you compare.
Lastly, use what you’ve learned to set clear goals for making your visual style better and better over time. With your visual audit complete, you’ll need to define the core elements of your design system.

Define Core Elements

Next, choose a color palette that speaks to your brand and choose fonts that convey the right personality. These choices lay the foundation for your visual language.

Color

Keep accessibility in mind from the outset. Colors are hardly effective if they can’t support readable, meaningful pairings. Anticipate which colors may be used together and prepare to check their contrast ratios and adjust as necessary. Grab your favorite contrast tool, like WebAIM’s WCAG 2.1 contrast checker, and set forth!

Choose a primary brand color. This is the essential color that defines your brand’s personality and promotes brand awareness, like Netflix’s red or Home Depot’s orange. From this color, derive a few lighter tints and darker shades so that you have the flexibility to pair your brand color with other colors while ensuring readable contrast.

Choose a neutral color to serve as a sort of canvas for your product, again with a few different tints and shades. Generally, these colors will be largely unsaturated and gray, but different products and audiences might warrant something bolder! Taking cues from the 60-30-10 rule of interior design, these colors account for 60%, or a large majority of, your web application, allowing your branded or semantic colors to grab attention. The tints and shades of your neutrals should always offer good contrast with other colors in your product.

Choose any necessary semantic colors. These colors convey specific meaning to your users, such as red for error states, green for success, and yellow or orange for warning. Depending on your needs, it’s generally a good idea to have tints and shades of each semantic color that can be used for backgrounds, icons, and text against your neutral colors.

Choose any number of accent colors for your brand. How many and what kind depends on the tone and attitude you want your product to have. Many products stick with just one brand color and their semantic colors, which allows the product to focus on clarity and usability. Other products employ a rainbow’s worth of accent colors, which can create high visual interest (though be careful not to hinder readability). Additional subtle, analogous colors can make your brand feel refined or pastoral, whereas louder, complementary or triadic colors can make your brand feel dynamic and exciting. Different strokes for different folks!

Circle back to accessibility. Falling in love with a color only to learn that it doesn’t offer great contrast is a unique kind of disappointment. (Believe me, it’s brutal.) But that doesn’t mean you have to kick it to the curb. Take stock of all of the colors in the palette you’ve created and decide on how they should be used in your product. One pairing might work well as paragraph text on a tinted background, while a lower contrast pairing may be well suited for a flashy, bold background with large text.

Typography

Choose a font (or two) that conveys the tone of your brand. If your brand’s font is especially unique, consider reserving this font for headings or other eye-catching text. For your body text, you’ll want a highly legible font for easy reading.

Choose font weights. Loading every possible weight from thin to black won’t make your site very performant. Decide on a few, distinct font weights that you can use to give different emphasis to your text. Variable fonts can make managing font weights especially easy: these fonts combine multiple weights into a single file, reducing its file size and making it a cinch to choose different font weights later if you change your mind.

Choose font sizes. Typography is key to establishing hierarchy in your content. Font size, in addition to font weight, plays a huge role in this hierarchy. You’ll want enough font sizes to cover different heading levels, body text, and supplementary details. Choosing a consistent ratio between font sizes, otherwise known as a typographic scale, can help ensure there’s enough variation in font sizes so that they’re easy to distinguish, all while maintaining a pleasing visual rhythm.

Spacing and Layout

Consider information density. Think about how folks use your product. Do they often need to scan or compare a lot of data? Do they read a page linearly with the goal of absorbing and retaining information? Your users’ goals should inform how densely you pack information on screen. A sales dashboard or an email application, for example, might warrant higher density than marketing materials or an onboarding flow. Once you determine how dense your product should generally be, the spacing rules in your design system should follow suit.

Choose a spacing scale. There isn’t a right or wrong way to codify spacing in your design system. Whether you like a linear scale (8, 16, 24, 32, etc.) or a geometric progression (8, 16, 32, 64, etc.), it’s all good! What’s important is that your scale is consistent, easy to design with, and creates a pleasing rhythm that works well for your users’ needs. Here’s a tip: Don’t have so many spacing values that it’s impossible to choose between them. Choosing whether there should be 8px or 16px between elements is much easier than choosing between 8px and 10px.

Establish responsive layout principles. Your product should be able to adapt to any device and screen size. Media breakpoints, grid systems, and intrinsic sizing are all options for supporting usage on anything from a smartphone to a television. Just promise us you won’t remove functionality on mobile; for many people, smartphones are their sole means to access the web.

Craft a Visual Language

Crafting a visual language involves creating guidelines for imagery and graphics. These guidelines ensure cohesive storytelling across all platforms, reinforcing your brand’s identity at every touchpoint.

Examples of a visual language may include:

Illustration guidelines
Photography style guide
Data visualization standards
Animation principles
UI component design rules
Brand voice and tone guidelines

Lastly, even though it’s not about looks, include rules for how your brand should sound in writing. This helps unify your content by giving everything the same voice.

Fun fact: Studies have shown that incorporating elements of controlled chaos or asymmetry in visual design systems can actually increase user engagement and brand recall. This phenomenon, known as the “Von Restorff effect,” hints at the idea that slightly breaking visual patterns in strategic ways can make certain elements more memorable, adding a dynamic edge to your design system without compromising overall consistency.

With your color palette locked, your type scale set, and your spacing rules established, you’ve got the bones of a real design system. But there’s one component that deserves its own conversation — one that’s deceptively simple on the surface and surprisingly deep once you get into it. We’re talking about icons. See you in Part 4.

The New Icon Wizard: Build an Icon Nobody’s Ever Made

2026-08-04T15:09:54Z

A wizard is never late, nor is he early. He arrives precisely when he means to.

The new Icon Wizard just arrived, and it hands you a brand-new toolbox and thousands upon thousands of icons to raid for parts. Stack them, shape them, combine them, resize them, and nudge them. So the next question is: what are you going to build?

No prompts, no AI. Just you, the tools, and however many layers it takes to get your creation juuuust right.

Anyone can experiment with the Wizard for free. And if you’ve got a Pro account, you can download your custom creation or save it to a Kit and use it anywhere Font Awesome works.

Conjure an Icon

And one more thing: the Wizard is shipping as a beta. So, if something breaks or gets wonky, tell us. That’s what helps make it ~~gooder~~ better.

Enter the Conjuring Contest!

Now onto the fun stuff. Welcome to the Icon Wizard icon-building contest extravaganza (or something like that)! Entry is open to anyone with an active Pro subscription. That’s what lets you save your creation to a Kit and enter it into the running.

How it Works

Build something unique with the Wizard, submit it to the Gallery and enter for the chance to win a free year of Font Awesome or some awesome swag. That’s all there is to it! Entries are open August 3, 2026 through September 7, 2026 and capped at 5 submissions, so don’t wait until the last minute. Approved entries typically go live in the gallery within a few business days of review.

Icon Categories

We’re judging in four categories, so there’s more than one way to win. You can create an icon that’s…

Most Useful — the icon you’d actually reach for in a real project
Most Creative — the “how did you even think of that?” entries
Best Remix — an existing Font Awesome icon, transformed into something new
Funniest — the one that hits the fa-team’s funny bone sweet spot

What You Get

The top prize is a free year of Pro. Category winners get a featured spot in the contest gallery. PLUS a shoutout in a blog post, newsletter, and on social media. Honorable mentions walk away with swag. And if we REALLY like your submission, we may even feature it in a future Font Awesome release.

Approved entries land in the Icon Wizard Gallery, and it’s not just for browsing. If you see something you like, you can save it straight to one of your own Kits.

So, go make something awesome. We’d love to see it!

WA 3.11: Data Grid, New Components, Plus Free Toast

2026-07-30T18:41:24Z

Everything in its place. 3.11 is about giving rows, pages, characters and parts the structure they’ve been missing.

📊 A Place for Your Data

<wa-data-grid> has arrived as experimental for Pro users. Sort, filter, search, select, reorder, resize and paginate; every row and column falls into place. Large datasets are virtualized automatically, only the rows on screen ever hit the DOM, so scrolling stays smooth whether you’ve got 50 rows or 50,000.

Set data and columns, use the features you need, and let the grid do the heavy lifting.

Don’t have Pro? Get it here

🔢 A Place for Every Page , and A Place for Every Character

Two new experimental components have been added to core, each one giving content some structure:

<wa-pagination> – set total and page-size, and watch long lists get carved into clean, numbered pages with previous/next controls, ready to sync via the wa-page-change event. Pairs naturally wa-data-grid, but works anywhere you’re paging through results.

<wa-otp-input> – a proper segmented input that gives verification code exactly as many slots as you need. With paste handling and keyboard navigation built in, set length and your’e off.

🍞 Toast Finds a New Home in Core

<wa-toast> and <wa-toast-item> moved from Pro to Core. Now everyone gets stackable, top layer notifications for success messages, errors, and status updates right out of the box. No upgrade required.

Drop a single <wa-toast> on your page and call .create() whenever you need to say something.

🎠 Carousels Slides Fall in Line

<wa-carousel> now has addSlide() and removeSlide() methods. So you can rearrange slides in and out on the fly, even with loop enabled. Perfect for carousels that use live data instead of a fixed set of slots.

🧩 Every Part Gets a Proper Name

Every component that renders a wrapper element now exposes a CSS part named after the component itself (button, details, carousel, etc.) alongside the current base part. Same goes for form control labels, which now expose form-control-label. base is softly deprecated, it’s not going anywhere for now. This update simply gives you a clearer name to reach for going forward.

🧰 Loose Ends? Tidied Up

As always, WA 3.11 ships with a bunch of fixes, color picker alpha handling, tree keyboard navigation, dialogs staying open when ad blockers hide them, and much more. Full details in the changelog.

Until next time! ✌️

The Building Blocks of a Visual Design System [Part II]

2026-07-23T15:52:06Z

Welcome back. In Part 1, we made the case for why a visual design system is worth caring about. Now it’s time to get into the actual stuff — the design system components that give your system its look, feel, and staying power.

So. Onto the design system components that make up the ingredients of a design system.

The key design system components include:

Color Palette: Primary, secondary, and accent colors
Typography: Font families, sizes, and hierarchies
Iconography: Style, usage guidelines, and custom icons
Imagery: Photography style, illustration guidelines
Layout: Grid systems, spacing rules, and responsive design principles
UI Components: Buttons, forms, cards, and other reusable elements

Once you have the basics of a design system nailed down, it’s important to maintain consistency across your entire brand.

The Power of Consistency

Think about the most successful companies; their visual identities are instantly recognizable. Here’s a little anecdote to underscore the point.

I have a loveable — but not particularly smart — Shi-tzu. And he loses his ever loving mind for pup-uccinos at Starbucks (a tiny cup of whipped cream). I’ve noticed on more than a few occasions that when we walk by a Starbucks, he wags his tail so hard that I start getting anxious that a doggie chiropractor bill may be in my future.

Now keep in mind, I wasn’t exclaiming to my dog that a pup-uccino was coming his way. But he either sees the sign or smells the coffee and he knows something good is imminent. I’d venture to guess that my dog has a nose for Starbucks and the cue probably isn’t the visual logo. But the point is, brand consistency ensures that every interaction with your brand is familiar and trustworthy. And if a dog can be trained on the consistency of experience, so can people.

This amusing anecdote illustrates a crucial point about the power of consistent branding. Let’s delve into the advantages of a consistent brand identity and see how it translates to the digital realm.

A consistent brand identity offers lots of pluses in the digital realm. It reduces cognitive load for users, making it easier for them to navigate and interact with your digital products. Consistency also increases brand recall and loyalty, as users become more familiar with your visual language. It also improves user interface learnability, allowing users to quickly understand and navigate your digital platforms. Ultimately, these factors contribute to enhanced overall user satisfaction.

Why Visual Design Systems Matter

There are many different types and sizes of digital devices. A good design system works well on all of them, making sure users can easily understand and use the product no matter what device they’re on.

When creating design systems, tech companies need to solve several problems related to making their products work on multiple devices. These include:

Making sure the content looks good on all screen sizes
Accounting for device interaction (like touching a screen vs. using a mouse)
Making the product run smoothly on devices with different capabilities
Ensuring the product is usable for people with disabilities across all devices

Solving these problems is important to give users a similar, high-quality experience no matter what device they use. Beyond the nuts and bolts of responsive design lies the art of visual storytelling.

Branding Beyond Words

Visual elements communicate brand values in ways words alone cannot. Believe it or not, visual elements can evoke the feels — subtle though they may be — create connections, and make your brand memorable. A strong visual design system ensures these elements are always aligned with your brand’s message.

When designing to make people feel something, there are lots of considerations. Colors can affect how people experience your brand. Where some colors might make people feel calm, others might make them feel excited. Using pictures, symbols, or icons that represent ideas can help explain things quickly in a way people will remember.

When your customer engages with your product, maybe you’ve included small, fun details that show off your brand’s personality and make the experience more enjoyable, and keep users interested.

You’ve got the design system components in hand Now let’s talk about what to actually do with them. In Part 3, we walk through a step-by-step process for auditing your current visuals, defining your core elements, and building a system that holds together under real-world pressure.

Pixel This! A Web Awesome Short-Guide to Visual Cohesion in Design Systems

2026-07-09T19:13:16Z

Part 1: Why Your Brand Needs a Visual Design System

In today’s online landscape, a website’s visual identity plays a critical role because everyone knows a great looking site is more than just aesthetics; it’s about creating a good experience for the user. And this is where a design system comes in. A well-crafted design system can be a transformative tool, ensuring consistency, enhancing usability, and anchoring your brand’s presence across all digital touch points.

Here’s why it matters:

User Experience: A cohesive visual system guides users intuitively through your product.
Brand Recognition: Consistent visuals build trust and familiarity with your audience.
Efficiency: A design system streamlines the development process, saving time and resources.
Scalability: As your product grows, a robust system ensures seamless expansion.

A few more words about user experience and efficiency

From the Web Awesome point of view, one of the most powerful influences of visual style on UX is how it informs how the user can expect to interact with the product, creating recognizable patterns so that they can predictably navigate and work the product.

Visuals that don’t properly set expectations for the user can be perceived as noisy, careless, or distracting, which negatively impacts how a user perceives the ease-of-use of a product.

Aesthetics are so important to usability, and it saddens me that UX evangelists can often dismiss their importance as frivolous or superficial — and this makes the Font Awesome ‘Possum sad. 😞

As for efficiency …

A design system makes a product resilient to the whims of designers. Design trends change, and designers often like to be on the frontlines of these changes. Design systems make this not only possible but seamless, allowing us to uniformly change the look and feel of a product with minimal impact to development throughput.

So in this blog, we’ve covered the why. But what exactly is a visual design system made of? Up next, we’ll break down the aesthetic building blocks that bring cohesion to your brand’s look and feel. Spoiler alert: color theory nerds, you’re gonna love it!