DEV Community: Jan

VSCode CSS `unknownAtRule` warning fix

Jan — Fri, 26 Sep 2025 15:07:12 +0000

Have you experienced unknownAtRule linter warning?

For recap, here are common CSS at-rules that will not result in CSS lint warning.

@import
@media
@supports
@layer
@font-face
@keyframes
@property
@page
@counter-style
@container

Most likely, you’re working with Tailwind CSS, which uses directives for special functionality and can cause the linter to complain.

A custom at-rules are allowed in CSS Syntax Module Level 3, but the linter will not know about them without your help.

That would be the case for Tailwind @theme, @apply directives, for example.

Rather than ignoring the unkonwnAtRules lint error by adding the following to the .vscode/settings.json:

{
  "css.lint.unknownAtRules": "ignore", // ignore | warning | error
}

here are two better alternatives:

1) First, if you use Tailwind CSS 4.x, install Tailwind CSS Intellisence and set the files.associations (I omitted the second step, the main reason this post exists 😆)
2) Second, have own whitelist of allowed at-rules.

1. Tailwind CSS 4.x, TW Intellisense plugin

Most likely you've encountered the unknownAtRule when working with the latest Tailwind CSS 4.x directives. Despite having Tailwind CSS Intellisence activated, you still see squiggly lint warnings. Most likely because you have not read the full docs for Recommended Settings. Don't forget to set your .vscode/settings.json:

  "files.associations": {
    "*.css": "tailwindcss"
  }

2. at-rules whitelist with own descriptions

You can create own whitelist of custom at-rules by adding their definitions into Custom Data.

(related: schema, custom-data-sample, custom-data-extension in package.json)

Inside .vscode/settings.json:

{
  "css.customData": [".vscode/css-custom-data.json"],
}

And add css-custom-data.json file with specific Tailwind directives:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@apply",
      "description": "Tailwind CSS directive for applying utility classes within custom CSS.",
      "references": [
        {
          "name": "@apply",
          "url": "https://tailwindcss.com/docs/functions-and-directives#apply"
        }
      ]
    },
    {
      "name": "@config",
      "description": "Tailwind CSS directive to load a legacy JavaScript-based configuration file.",
      "references": [
        {
          "name": "@config",
          "url": "https://tailwindcss.com/docs/functions-and-directives#config"
        }
      ]
    },
    {
      "name": "@custom-variant",
      "description": "Tailwind CSS directive for defining custom variants.",
      "references": [
        {
          "name": "@custom-variant",
          "url": "https://tailwindcss.com/docs/plugins#adding-variants"
        }
      ]
    },
    {
      "name": "@layer",
      "description": "Tailwind CSS directive for organizing custom styles into cascade layers.",
      "references": [
        {
          "name": "@layer",
          "url": "https://tailwindcss.com/docs/functions-and-directives#layer"
        }
      ]
    },
    {
      "name": "@plugin",
      "description": "Tailwind CSS directive to load a legacy JavaScript-based plugin.",
      "references": [
        {
          "name": "@plugin",
          "url": "https://tailwindcss.com/docs/plugins"
        }
      ]
    },
    {
      "name": "@source",
      "description": "Tailwind CSS directive to specify source files for content detection or to safelist utilities.",
      "references": [
        {
          "name": "@source",
          "url": "https://tailwindcss.com/docs/content-configuration"
        }
      ]
    },
    {
      "name": "@theme",
      "description": "Tailwind CSS directive for defining custom design tokens like fonts, colors, and breakpoints.",
      "references": [
        {
          "name": "@theme",
          "url": "https://tailwindcss.com/docs/theme"
        }
      ]
    },
    {
      "name": "@utility",
      "description": "Tailwind CSS directive to add custom utilities to the framework.",
      "references": [
        {
          "name": "@utility",
          "url": "https://tailwindcss.com/docs/plugins#adding-utilities"
        }
      ]
    },
    {
      "name": "@variant",
      "description": "Tailwind CSS directive to apply a variant to styles in your CSS.",
      "references": [
        {
          "name": "@variant",
          "url": "https://tailwindcss.com/docs/plugins#adding-variants"
        }
      ]
    }
  ]
}

Reload the window with Command Palette (⌘ + ⇧ + P) "Deveper: Reload Window" to apply.

And voila:

Summary:

Custom at-rules lint errors can be fixed with right plugin that is correctly set or by creating custom user rules.

Sometimes having a meaningful defaults can't be expected. (It is unclear if this was the case of Tailwind CSS Intellisence plugin)

User Friendly Image Optimization Tool

Jan — Mon, 19 May 2025 16:22:57 +0000

There are many online image convertors and optimizers. A comprehensive list can be found in Powerful Image Optimization - Smashing Magazine article (it is dated 2022, so you can judge which survived long term).

Here are two tips for open sourced, locally run tool.

SVGOMG SVGOMG is GUI implementation of SVGO with many settings to optimize your SVG.
ImgOptim is mac app tool with simple interface integrating common image optimization CLI tools to optimize your jpeg, svg, gif, png.

Few open source projects made me instantly donate!
Send them love and support.

Dealing With Web Fonts

Jan — Mon, 05 May 2025 16:24:36 +0000

When starting a web project (especially from scratch), a font is one of the questions that can spill the project into red relatively fast.

Understand the Typography evokes emotions and as such it effects how people perceive, relate, trust and make buying decisions about the product, company or service.

As a developer you take care about performance, cross platform support and technical accessibility.

First, identify the typeface—and specific font styles—you need to implement (ask your designer if in doubt 😆).
Deliver. Start with web-safe fonts, fonts already existing in your UI toolkit/CSS framework) and fonts hosted on common font hosting platforms such as Google Fonts, Adobe Fonts, Monotype

If dependence on, or access to a 3rd party provider is a concern, self-host your fonts for total control.

High level points:

You need a license to self-host a downloaded type.
There are many font file formats (svg, otf, ttf, woff, woff2).
Modern web format is woff (Web Open Font Format) with ~97% browser support. Version 2 is using Brotli compression and is ~20% - 50% more efficient.

Cool links:

Pair fonts with AI on Fontjoy
Edit Glyphs in glyphr studio
Learn Glyphs on Glyphs

Sandbox Tests:

Enjoy selecting, managing and deploying fonts faster.
It used to be much harder..

4 Ways to Include SVG in HTML and a11y consideration

Jan — Sat, 26 Apr 2025 03:20:09 +0000

Here are 4 common approaches for including SVGs in HTML, along with a sample examples, comparison tables and accessibility considerations:

1. Using `<object>`

<object type="image/svg+xml" data="icon.svg"></object>

2. Inline SVG

<svg width="100" height="100" viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" fill="skyblue" />
</svg>

3. SVG as a Background Image (CSS)

<div class="icon"></div>

<style>
  .icon {
    width: 100px;
    height: 100px;
    background-image: url('icon.svg');
    background-size: cover;
  }
</style>

4. SVG as an `<img>`

<img src="icon.svg" alt="Icon" width="100" height="100">

Comparison Table

Method	Advantages	Disadvantages
`<object>`	- Loads external SVG - Supports fallback - Separate from DOM	- No direct CSS/JS access to inner elements - More HTTP requests
Inline SVG	- Full control via CSS & JS - Animatable - Accessible in DOM	- Clutters HTML - Can't reuse easily without duplication
Background Image	- Clean HTML - Good for decorative use - CSS control on container	- No control over SVG internals - Not accessible or interactive
`<img>`	- Simple & semantic - Easy to use - Can include alt text	- No CSS/JS access to inner elements - Limited interactivity

SVG & Accessibility

✅ 1. `<object>` – Moderate Accessibility

<object type="image/svg+xml" data="icon.svg">Fallback text</object>

Pros:

You can provide fallback text for screen readers and browsers that don’t support SVG.
External SVGs can contain their own <title>, <desc>, and ARIA attributes.

Cons:

Screen readers might not access the inner SVG content unless it’s well-structured inside the file.
Accessibility depends heavily on how the external SVG file is authored.

✅ 2. Inline SVG – Best Accessibility

<svg role="img" aria-labelledby="titleId descId">
  <title id="titleId">Blue circle</title>
  <desc id="descId">A simple circle shape filled with sky blue</desc>
  <circle cx="50" cy="50" r="40" fill="skyblue" />
</svg>

Pros:

You have full control over accessibility:
- Add <title> and <desc> for screen readers.
- Use role="img" and aria-* attributes.
Screen readers can interpret the SVG directly.
Fully navigable in the accessibility tree.

Cons:

More verbose in the HTML.
You must manually manage ids and aria references for accessibility.

🚫 3. SVG as Background Image – Not Accessible

background-image: url('icon.svg');

Pros:

Clean for purely decorative icons.

Cons:

Not accessible to screen readers at all.
Treated as a decorative style, not as content.
Can't provide alt text or semantic meaning.
Should only be used for purely decorative graphics.

⚠️ 4. SVG as `<img>` – Limited Accessibility

<img src="icon.svg" alt="A sky blue circle icon">

Pros:

Uses the standard alt attribute.
Treated like any other image: accessible if alt is meaningful.
Good for simple icons, logos, or illustrations.

Cons:

Cannot describe or access inner elements.
Can't be made interactive.
Can’t use SVG-native accessibility features like <title> or <desc> unless you're using <object> or inline SVG.

🎯 Recommendation Based on Accessibility

Use Case	Recommended Approach
Interactive icons	Inline SVG
Decorative backgrounds	CSS background image (with `aria-hidden`)
Semantic, non-interactive icons	`<img>` with descriptive `alt`
Rich SVG with built-in a11y	`<object>` (only if SVG is authored well)

QA Time:

1. 🧠 What are `<title>` and `<desc>` in SVG?

Let's revisit the use of <title> and <desc> elements inside SVGs one more time. These elements are crucial for accessibility, especially when SVGs are inline and part of meaningful content (like icons, logos, or illustrations conveying info).

Element	Purpose
`<title>`	Gives the SVG a short, accessible name (like `alt` text for images).
`<desc>`	Provides a longer, optional description (context or explanation).

They are read by screen readers and help users who can’t see the image understand its meaning.

✅ Basic Example

<svg role="img" aria-labelledby="svgTitle svgDesc" xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <title id="svgTitle">Information icon</title>
  <desc id="svgDesc">A blue circle with a lowercase letter i in the center</desc>
  <circle cx="50" cy="50" r="45" fill="skyblue"/>
  <text x="50" y="60" font-size="40" text-anchor="middle" fill="white">i</text>
</svg>

🧩 Key Parts:

role="img": Tells assistive tech this is an image, not just a decorative shape.
aria-labelledby="svgTitle svgDesc": Connects the text to the SVG.
<title>: Serves like alt text.
<desc>: Optional, adds detail.

🗂 When to Use Them

Use Case	Use `<title>`?	Use `<desc>`?
Logo or brand icon	✅ Yes	Optional
UI icon with meaning	✅ Yes	Optional
Decorative image	❌ No	❌ No
Complex charts or infographics	✅ Yes	✅ Yes

For decorative icons, you should instead use:

<svg aria-hidden="true" focusable="false" ...>
  <!-- no title or desc -->
</svg>

2. Can svg omit the `xmlns`?

Yes — when used inline inside an HTML document, the xmlns attribute is not required.

So this is perfectly valid inline HTML5 SVG:

<svg role="img" aria-labelledby="titleId descId">
  <title id="titleId">Blue circle</title>
  <desc id="descId">A simple circle shape filled with sky blue</desc>
  <circle cx="50" cy="50" r="40" fill="skyblue" />
</svg>

This works fine in modern browsers and supports accessibility.

⚠️ When is `xmlns` required?

Only in these cases:

Context	`xmlns` Required?	Why?
Inline in HTML	❌ No	Handled by browser’s HTML parser
SVG file (standalone .svg)	✅ Yes	Required for XML validation
Inline in XHTML	✅ Yes	Because XHTML is XML-based
Copied into XML/MathML	✅ Yes	Needs proper XML namespacing

Example for standalone SVG files:

<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <circle cx="50" cy="50" r="40" fill="skyblue" />
</svg>

Without the xmlns, the file won't validate as an SVG document and could cause rendering issues in some tools or older XML-based workflows.

🧪 Tips and Gotchas

🔢 1. Use Unique `id`s

Avoid duplicate ids like title or desc, especially in SPAs or when using SVGs multiple times.

<title id="infoIconTitle">Info icon</title>

♿ 2. Make It Focusable if Interactive

If the SVG is clickable (like a button):

<svg role="img" tabindex="0" ...>...</svg>

Or better: wrap it in a <button> or add keyboard handlers.

⚠️ 3. Don’t Rely on `<title>` as a Tooltip

Browsers often don’t show the SVG <title> as a tooltip like they do for HTML. Use title="" on the container element or tooltips for visual hints.

🛠️ 4. Screen Reader Testing

Test with real screen readers (VoiceOver, NVDA, etc.) — support is decent but can vary slightly between them.

Test the examples live.

And that's a wrap!

TypeScript Generics Propagation in useOptimistic react hook

Jan — Fri, 18 Apr 2025 19:13:17 +0000

Summary

Generics enable reusable, type-safe code by parameterizing types, and their propagation ensures that these parameterized types are correctly applied or inferred in various contexts, such as function calls, object compositions, or React components (like the useOptimistic hook example). These benefits come at a cost: generics can pose a steep learning curve and increased complexity, particularly with nested structures, potentially leading to ambiguity in code.

1. What Are TypeScript Generics?

Generics allow you to define functions, interfaces, or classes that work with a variety of types while preserving type safety. Instead of hardcoding a specific type, you use a placeholder (e.g., T) that is specified when the generic is used.

Example:

function identity<T>(value: T): T {
  return value;
}

const num = identity<number>(42); // T is number
const str = identity<string>("hello"); // T is string

Here, T is a generic type parameter that propagates through the function, ensuring the input and output types are the same.

If you’ve read the official TypeScript docs and explored more digestible examples, you might still find the following useOptimistic React hook example challenging:

const [optimisticMessages, addOptimisticMessage] = useOptimistic<Message[], string>(
  messages,
  (state, newMessage) => [
    ...state,
    {
      text: newMessage,
      sending: true,
    },
  ]
);

Can you clearly articulate what <Message[], string> means?

If so, great job—stop reading here! 👍

If not, let’s dive deeper.

Type Inference with `useOptimistic`

TypeScript’s type inference can sometimes eliminate the need for explicit generic annotations. For example, if the messages array is already typed as Message[] and the newMessage parameter is annotated as string, TypeScript can infer the generics:

const [optimisticMessages, addOptimisticMessage] = useOptimistic(messages, (state, newMessage: string) => [
  ...state,
  { text: newMessage, sending: true },
]);

Here, TypeScript infers T as Message[] from messages and A as string from newMessage. Explicit generics (<Message[], string>) are necessary only when TypeScript cannot infer types (e.g., with ambiguous or untyped inputs) or when you want to enforce specific types.

`useOptimistic` with User-Friendly Typing

To build a mental model, consider this mock implementation:

function useOptimistic<StateType, UpdateType>(
  initialState: StateType,
  applyUpdate: (currentState: StateType, update: UpdateType) => StateType
): [StateType, (update: UpdateType) => void] {
  const [state, setState] = React.useState(initialState);

  function addOptimisticUpdate(update: UpdateType) {
    setState((prevState) => applyUpdate(prevState, update));
  }

  return [state, addOptimisticUpdate];
}

This shows how StateType and UpdateType are used in the hook.

`useOptimistic` Generic Signature

The previous example is verbose. Let’s simplify it using T and A as generic parameters:

function useOptimistic<T, A>(state: T, updateFn: (state: T, action: A) => T): [T, (action: A) => void];

(The real-world useOptimistic signature can be found in the React source code .)

Returning to the hook usage:

const [optimisticMessages, addOptimisticMessage] = useOptimistic<Message[], string>(
  // ...
);

Now, the meaning of <Message[], string> becomes clearer:

T: The type of the state (e.g., Message[]).
- This defines the type of the optimistic state being managed.
- Here, optimisticMessages is typed as an array of Message objects.
A: The type of the action (e.g., string).
- This defines the type of data passed to the updater function (addOptimisticMessage).
- In this case, string represents the text of a new message used to create an optimistic message.

2. Mechanics of Generics Propagation

Generics propagation occurs when a generic type is passed or inferred through a chain of operations, such as:

Function calls
Return types
Object or array manipulations
Component props or hooks in React

The TypeScript compiler tracks the generic type (T, A, etc.) and ensures it is consistently applied or inferred based on usage. Propagation can happen explicitly (via type annotations) or implicitly (via type inference).

In React, generics propagation is common in hooks, components, and utilities, ensuring type safety for props, state, or actions. Let’s analyze the useOptimistic hook:

1. Explicit Type Specification:

The generic <Message[], string> is explicitly provided when calling useOptimistic.
T is set to Message[], meaning the state (optimisticMessages) and the first argument to the update function (state) are Message[].
A is set to string, meaning the action (newMessage) and the argument to addOptimisticMessage are string.

2. Propagation to State:

The hook returns optimisticMessages as T (Message[]), so optimisticMessages is typed as Message[].
This ensures that operations on optimisticMessages (e.g., mapping or rendering) treat it as an array of Message objects.

3. Propagation to Update Function:

The update function (state: T, newMessage: A) => T becomes (state: Message[], newMessage: string) => Message[].
The generic T propagates to state and the return type, ensuring the function returns a Message[].
The generic A propagates to newMessage, ensuring it’s a string.

4. Propagation to Action Handler:

The hook returns addOptimisticMessage as (action: A) => void, which becomes (action: string) => void.
When addOptimisticMessage("new message") is called, TypeScript ensures the argument is a string, propagating the A type.

Generics propagation ensures that:

The state (optimisticMessages) remains Message[] throughout the component lifecycle.
The action (addOptimisticMessage) only accepts string inputs.
The update function produces a valid Message[], preventing type mismatches (e.g., adding an invalid object to the array).

3. Conclusion

Understanding TypeScript basics is a prerequisite before diving into generics. By mastering generics propagation, we can:

Write reusable, type-safe code.
Ensure hooks and components handle data consistently.
Catch errors early through TypeScript’s type checking.

Common pitfalls are overly complex generic constraints that make code harder to read or maintain, incorrect type assumptions that lead to type errors (e.g., assuming a generic type is more specific than it is). Simplifying generics and leveraging TypeScript’s inference can often reduce complexity while maintaining safety.

CSS-in-JS: Pros and cons

Jan — Fri, 11 Apr 2025 16:43:56 +0000

Summary

CSS-in-JS provides benefits like colocation, scoping, dynamic styling, and type-safety, for React-like frameworks. However, it can introduce runtime performance costs and added setup complexity. Modern libraries now offer static extraction and build support for SSR.

Brief History

CSS-in-JS emerged in 2014 with libraries like JSS and React’s inline styles, aiming to integrate styling with JavaScript for component-driven frameworks.

The 2016 release of styled-components popularized the approach, offering a clean syntax and React integration.

By 2018, Emotion and others expanded the ecosystem, addressing performance and flexibility. In server-side rendering (SSR) scenarios, CSS-in-JS libraries like styled-components and Emotion enable styles to be collected during rendering and embedded in the initial HTML response, ensuring faster page loads and preventing flash of unstyled content (FOUC).

Static extraction libraries like Linaria (2020) and Vanilla Extract (2021) later minimized runtime costs.

Why CSS-in-JS?

1. Colocation: Styles stay with components, easing maintenance. Example using styled-components:

   import styled from 'styled-components';
   const Button = styled.button`
     background: blue;
     color: white;
     padding: 10px;
   `;

2. Scoping: Component-scoped styles prevent leaks. Emotion and styled-components generate unique class names, avoiding conflicts without BEM.

3. Dynamic Styles: JavaScript enables runtime styles via props or state

   const Button = styled.button`
     background: ${props => (props.primary ? 'blue' : 'gray')};
     font-size: ${props => props.size || '16px'};
   `;

4. Type-Safety: TypeScript catches errors early.

   interface ButtonProps {
     primary?: boolean;
   }
   const Button = styled.button<ButtonProps>`
     background: ${props => (props.primary ? 'blue' : 'gray')};
   `;

Why Not CSS-in-JS?

1. Performance Overhead: Runtime style generation slows rendering versus static CSS. Static extraction mitigates but doesn’t eliminate this.

2. Learning Curve: New APIs and tooling (Babel, Webpack) add complexity. Teams used to CSS or Tailwind may prefer simpler options.

Modern CSS-in-JS Libraries

Before Static Extraction

styled-components: Template literals for React-friendly styling.
Emotion: Lightweight, with CSS prop and TypeScript support.
JSS: Object-based styles, less common in React.

See: React: style-components Example

After Static Extraction

Linaria: Zero-runtime, styled-components-like syntax, extracts to CSS.
Vanilla Extract: Type-safe, JavaScript objects, generates static CSS.
Emotion (@emotion/css): Supports static extraction for build-time CSS.
Panda CSS: Utility-first, static CSS with CSS-in-JS ergonomics.

See: React: panda-css Example

UI Libraries and CSS-in-JS Usage

Material-UI (MUI): Uses Emotion (v5+), supports styled-components via plugin, JSS in older versions.
Chakra UI: Emotion-based styled-system for dynamic, theme-driven styles.
Mantine: Custom CSS-in-JS, Emotion-like, with static extraction.
Ant Design: CSS Modules primarily, supports Emotion/styled-components via integrations.
Radix UI: No CSS-in-JS; uses vanilla CSS or Tailwind for unstyled primitives.

Conclusion

CSS-in-JS offers colocation, scoping, dynamic styles, and type-safety, for React-like frameworks. Runtime performance and setup complexity are drawbacks. Static extraction tools like Linaria and Vanila Extract blend CSS-in-JS benefits with static CSS speed. UI libraries like MUI and Chakra UI favor Emotion, while Radix avoids CSS-in-JS for flexibility. Based on app scale and team skills; simplicity may favor CSS Modules or Tailwind.

DEV Community: Jan

VSCode CSS `unknownAtRule` warning fix

1. Tailwind CSS 4.x, TW Intellisense plugin

2. at-rules whitelist with own descriptions

Summary:

User Friendly Image Optimization Tool

Dealing With Web Fonts

High level points:

Cool links:

Sandbox Tests:

4 Ways to Include SVG in HTML and a11y consideration

1. Using <object>

2. Inline SVG

3. SVG as a Background Image (CSS)

4. SVG as an <img>

Comparison Table

SVG & Accessibility

✅ 1. <object> – Moderate Accessibility

✅ 2. Inline SVG – Best Accessibility

🚫 3. SVG as Background Image – Not Accessible

⚠️ 4. SVG as <img> – Limited Accessibility

🎯 Recommendation Based on Accessibility

QA Time:

1. 🧠 What are <title> and <desc> in SVG?

✅ Basic Example

🧩 Key Parts:

🗂 When to Use Them

2. Can svg omit the xmlns?

⚠️ When is xmlns required?

🧪 Tips and Gotchas

🔢 1. Use Unique ids

♿ 2. Make It Focusable if Interactive

⚠️ 3. Don’t Rely on <title> as a Tooltip

🛠️ 4. Screen Reader Testing

TypeScript Generics Propagation in useOptimistic react hook

Summary

1. What Are TypeScript Generics?

Type Inference with useOptimistic

useOptimistic with User-Friendly Typing

useOptimistic Generic Signature

2. Mechanics of Generics Propagation

Generics propagation ensures that:

3. Conclusion

CSS-in-JS: Pros and cons

Summary

Brief History

Why CSS-in-JS?

Why Not CSS-in-JS?

Modern CSS-in-JS Libraries

Before Static Extraction

After Static Extraction

UI Libraries and CSS-in-JS Usage

Conclusion

1. Using `<object>`

4. SVG as an `<img>`

✅ 1. `<object>` – Moderate Accessibility

⚠️ 4. SVG as `<img>` – Limited Accessibility

1. 🧠 What are `<title>` and `<desc>` in SVG?

2. Can svg omit the `xmlns`?

⚠️ When is `xmlns` required?

🔢 1. Use Unique `id`s

⚠️ 3. Don’t Rely on `<title>` as a Tooltip

Type Inference with `useOptimistic`

`useOptimistic` with User-Friendly Typing

`useOptimistic` Generic Signature