From 747c6edb4fb8e6e6ca43308c33f519bdd9483bef Mon Sep 17 00:00:00 2001
From: mizdra <pp.mizdra@gmail.com>
Date: Sun, 5 Jul 2026 22:12:13 +0900
Subject: [PATCH 1/3] feat(core, ts-plugin, codegen, vscode): support scoping
 container names via `cmkOptions.container`

---
 .changeset/container-option.md                |   8 +
 AGENTS.md                                     |   4 +-
 README.md                                     |  17 ++
 docs/glossary.md                              |   2 +-
 packages/codegen/src/project.ts               |   1 +
 packages/core/src/config.test.ts              |  16 ++
 packages/core/src/config.ts                   |  13 ++
 packages/core/src/parser/animation-parser.ts  |   8 +-
 packages/core/src/parser/composes-parser.ts   |   2 +-
 .../core/src/parser/container-parser.test.ts  | 157 ++++++++++++++++++
 packages/core/src/parser/container-parser.ts  |  94 +++++++++++
 .../core/src/parser/css-module-parser.test.ts |  23 +++
 packages/core/src/parser/css-module-parser.ts |  31 +++-
 .../core/src/parser/dashed-ident-parser.ts    |   4 -
 .../{decl-value-location.ts => util.ts}       |   5 +
 packages/core/src/test/css-module.ts          |   3 +-
 packages/core/src/test/faker.ts               |   1 +
 packages/ts-plugin/src/language-plugin.ts     |   1 +
 packages/vscode/schemas/tsconfig.schema.json  |   6 +
 19 files changed, 376 insertions(+), 20 deletions(-)
 create mode 100644 .changeset/container-option.md
 create mode 100644 packages/core/src/parser/container-parser.test.ts
 create mode 100644 packages/core/src/parser/container-parser.ts
 rename packages/core/src/parser/{decl-value-location.ts => util.ts} (65%)

diff --git a/.changeset/container-option.md b/.changeset/container-option.md
new file mode 100644
index 00000000..45c84268
--- /dev/null
+++ b/.changeset/container-option.md
@@ -0,0 +1,8 @@
+---
+'@css-modules-kit/core': minor
+'@css-modules-kit/ts-plugin': minor
+'@css-modules-kit/codegen': minor
+'css-modules-kit-vscode': minor
+---
+
+feat(core, ts-plugin, codegen, vscode): support scoping container names via `cmkOptions.container`
diff --git a/AGENTS.md b/AGENTS.md
index b6d285c0..71feb2c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -110,8 +110,8 @@ function myFunction() {
 
 ## Glossary
 
-- **Token**: A generic term for things exported by CSS Modules, such as class names, `@value` definitions, `@keyframes` names, and `<dashed-ident>`s (custom properties, when `cmkOptions.dashedIdents` is enabled).
-- **Token reference**: A usage of a token elsewhere in the CSS. Currently produced for `animation-name: <name>` and `composes: <name>`. There are two kinds:
+- **Token**: A generic term for things exported by CSS Modules, such as class names, `@value` definitions, `@keyframes` names, container names (when `cmkOptions.container` is enabled), and `<dashed-ident>`s (custom properties, when `cmkOptions.dashedIdents` is enabled).
+- **Token reference**: A usage of a token elsewhere in the CSS. Currently produced for `animation-name: <name>`, `composes: <name>`, and `@container <name> (...)`. There are two kinds:
   - **Local token reference**: References a token available in the current file. The token may be defined in the same file (e.g. `@keyframes`) or imported via `@import` / `@value ... from`.
   - **External token reference**: References tokens exported by another file, like `composes: <name> ... from '<specifier>'`. One reference corresponds to one `from` clause and holds an entry per referenced token.
 - **Diagnostic**: An object representing errors or warnings
diff --git a/README.md b/README.md
index fad1f866..22e97b47 100644
--- a/README.md
+++ b/README.md
@@ -248,6 +248,23 @@ Determines whether to generate the [token](docs/glossary.md#token) of `<dashed-i
 }
 ```
 
+### `cmkOptions.container`
+
+Type: `boolean`, Default: `false`
+
+Determines whether to generate the [token](docs/glossary.md#token) of container names (used in `container-name`, the `container` shorthand, and `@container`) in the d.ts file.
+
+```jsonc
+{
+  "compilerOptions": {
+    // ...
+  },
+  "cmkOptions": {
+    "container": true,
+  },
+}
+```
+
 ## Limitations
 
 Due to implementation constraints and technical reasons, css-modules-kit has various limitations.
diff --git a/docs/glossary.md b/docs/glossary.md
index 7d44d70b..ce2c5307 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -21,7 +21,7 @@ For example, consider the following CSS file:
 }
 ```
 
-In this case, `a_1`, `a_2`, `a_3`, `a_4`, `b_1` and `b_2_alias` are tokens. If `dashedIdents` option is `true`, `--a-5` is also a token.
+In this case, `a_1`, `a_2`, `a_3`, `a_4`, `b_1` and `b_2_alias` are tokens. If `dashedIdents` option is `true`, `--a-5` is also a token. If `container` option is `true`, container names used in `container-name`, the `container` shorthand, and `@container` are also tokens.
 
 ## Corresponding Component File
 
diff --git a/packages/codegen/src/project.ts b/packages/codegen/src/project.ts
index fc5cca94..89ac6c55 100644
--- a/packages/codegen/src/project.ts
+++ b/packages/codegen/src/project.ts
@@ -157,6 +157,7 @@ export function createProject(args: ProjectArgs): Project {
       includeSyntaxError: true,
       animation: config.animation,
       dashedIdents: config.dashedIdents,
+      container: config.container,
     });
   }
 
diff --git a/packages/core/src/config.test.ts b/packages/core/src/config.test.ts
index 7aebb228..db07327f 100644
--- a/packages/core/src/config.test.ts
+++ b/packages/core/src/config.test.ts
@@ -28,6 +28,7 @@ describe('readConfigFile', () => {
         prioritizeNamedImports: false,
         animation: true,
         dashedIdents: false,
+        container: false,
         enabled: false,
         compilerOptions: expect.any(Object),
         wildcardDirectories: [{ fileName: iff.rootDir, recursive: true }],
@@ -50,6 +51,7 @@ describe('readConfigFile', () => {
             "prioritizeNamedImports": true,
             "animation": false,
             "dashedIdents": true,
+            "container": true,
             "enabled": true
           }
         }
@@ -65,6 +67,7 @@ describe('readConfigFile', () => {
         prioritizeNamedImports: true,
         animation: false,
         dashedIdents: true,
+        container: true,
         enabled: true,
         compilerOptions: expect.objectContaining({
           module: ts.ModuleKind.ESNext,
@@ -90,6 +93,7 @@ describe('readConfigFile', () => {
               "prioritizeNamedImports": true,
               "animation": false,
               "dashedIdents": true,
+              "container": true,
               "enabled": true
             }
           }
@@ -106,6 +110,7 @@ describe('readConfigFile', () => {
           prioritizeNamedImports: true,
           animation: false,
           dashedIdents: true,
+          container: true,
           enabled: true,
           compilerOptions: expect.objectContaining({
             module: ts.ModuleKind.ESNext,
@@ -393,6 +398,17 @@ describe('readConfigFile', () => {
         },
       ]);
     });
+    test('reports an error if `container` is not a boolean', async () => {
+      const iff = await createIFF({
+        'tsconfig.json': '{ "cmkOptions": { "container": 1 } }',
+      });
+      expect(readConfigFile(iff.rootDir).diagnostics).toStrictEqual([
+        {
+          category: 'error',
+          text: `\`container\` in ${iff.paths['tsconfig.json']} must be a boolean.`,
+        },
+      ]);
+    });
   });
   describe('deprecated `keyframes` option', () => {
     test('adopts the `keyframes` value as `animation` and reports a deprecation warning', async () => {
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
index 36039402..4947195e 100644
--- a/packages/core/src/config.ts
+++ b/packages/core/src/config.ts
@@ -20,6 +20,7 @@ export interface CMKConfig {
   prioritizeNamedImports: boolean;
   animation: boolean;
   dashedIdents: boolean;
+  container: boolean;
   /**
    * A root directory to resolve relative path entries in the config file to.
    * This is an absolute path.
@@ -81,6 +82,7 @@ interface UnnormalizedRawConfig {
   animation?: boolean;
   keyframes?: boolean;
   dashedIdents?: boolean;
+  container?: boolean;
 }
 
 /**
@@ -196,6 +198,16 @@ function parseRawData(raw: unknown, tsConfigSourceFile: ts.TsConfigSourceFile, b
         });
       }
     }
+    if ('container' in raw.cmkOptions) {
+      if (typeof raw.cmkOptions.container === 'boolean') {
+        result.config.container = raw.cmkOptions.container;
+      } else {
+        result.diagnostics.push({
+          category: 'error',
+          text: `\`container\` in ${tsConfigSourceFile.fileName} must be a boolean.`,
+        });
+      }
+    }
     if ('namedExports' in raw.cmkOptions) {
       if (typeof raw.cmkOptions.namedExports === 'boolean') {
         result.config.namedExports = raw.cmkOptions.namedExports;
@@ -316,6 +328,7 @@ export function readConfigFile(project: string): CMKConfig {
     prioritizeNamedImports: parsedTsConfig.config.prioritizeNamedImports ?? false,
     animation: parsedTsConfig.config.animation ?? parsedTsConfig.config.keyframes ?? true,
     dashedIdents: parsedTsConfig.config.dashedIdents ?? false,
+    container: parsedTsConfig.config.container ?? false,
     enabled: parsedTsConfig.config.enabled ?? false,
     basePath,
     configFileName,
diff --git a/packages/core/src/parser/animation-parser.ts b/packages/core/src/parser/animation-parser.ts
index 297d07d8..f4a5fe7a 100644
--- a/packages/core/src/parser/animation-parser.ts
+++ b/packages/core/src/parser/animation-parser.ts
@@ -1,7 +1,8 @@
 import type { Declaration } from 'postcss';
 import postcssValueParser from 'postcss-value-parser';
 import type { DiagnosticWithDetachedLocation, TokenReference } from '../type.js';
-import { calcDeclValueLoc } from './decl-value-location.js';
+import { calcDeclValueLoc } from './util.js';
+import { VALID_IDENT_RE } from './util.js';
 
 const ANIMATION_NAME_PROP_RE = /^(?:-(?:webkit|moz|o|ms)-)?animation-name$/iu;
 const ANIMATION_PROP_RE = /^(?:-(?:webkit|moz|o|ms)-)?animation$/iu;
@@ -60,11 +61,6 @@ const ANIMATION_SHORTHAND_RESERVED_KEYWORDS = new Set([
   'paused',
 ]);
 
-// A valid CSS identifier, including `<dashed-ident>`. Excludes `<time>` (`3s`), `<number>` (`2`),
-// and other non-ident words. We don't validate `hex digits`, because it is the job of linters.
-const VALID_IDENT_RE =
-  /^-?([a-zA-Z\u0080-\uFFFF_]|(\\[^\r\n\f])|-(?![0-9]))((\\[^\r\n\f])|[a-zA-Z\u0080-\uFFFF_0-9-])*$/u;
-
 interface ParseAnimationResult {
   references: TokenReference[];
   diagnostics: DiagnosticWithDetachedLocation[];
diff --git a/packages/core/src/parser/composes-parser.ts b/packages/core/src/parser/composes-parser.ts
index 7e42845c..fbff4df8 100644
--- a/packages/core/src/parser/composes-parser.ts
+++ b/packages/core/src/parser/composes-parser.ts
@@ -6,7 +6,7 @@ import type {
   LocalTokenReference,
   TokenReference,
 } from '../type.js';
-import { calcDeclValueLoc } from './decl-value-location.js';
+import { calcDeclValueLoc } from './util.js';
 
 const COMPOSES_PROP_RE = /^composes$/iu;
 
diff --git a/packages/core/src/parser/container-parser.test.ts b/packages/core/src/parser/container-parser.test.ts
new file mode 100644
index 00000000..b27d098d
--- /dev/null
+++ b/packages/core/src/parser/container-parser.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, test } from 'vite-plus/test';
+import { fakeAtRule, fakeDeclaration } from '../test/ast.js';
+import {
+  isContainerAtRuleName,
+  isContainerNameProp,
+  isContainerProp,
+  parseContainerAtRule,
+  parseContainerNameProp,
+  parseContainerProp,
+} from './container-parser.js';
+
+describe('isContainerNameProp', () => {
+  test.each([
+    ['container-name', true],
+    ['Container-Name', true],
+    ['container', false],
+    ['color', false],
+  ])('%s -> %s', (prop, expected) => {
+    expect(isContainerNameProp(prop)).toBe(expected);
+  });
+});
+
+describe('isContainerProp', () => {
+  test.each([
+    ['container', true],
+    ['Container', true],
+    ['container-name', false],
+    ['color', false],
+  ])('%s -> %s', (prop, expected) => {
+    expect(isContainerProp(prop)).toBe(expected);
+  });
+});
+
+describe('isContainerAtRuleName', () => {
+  test.each([
+    ['container', true],
+    ['Container', true],
+    ['media', false],
+  ])('%s -> %s', (name, expected) => {
+    expect(isContainerAtRuleName(name)).toBe(expected);
+  });
+});
+
+describe('parseContainerNameProp', () => {
+  test('extracts tokens from container-name declaration', () => {
+    const decl = fakeDeclaration('.a_1 { container-name: foo }');
+    expect(parseContainerNameProp(decl)).toMatchInlineSnapshot(`
+      [
+        {
+          "declarationLoc": {
+            "end": {
+              "column": 27,
+              "line": 1,
+              "offset": 26,
+            },
+            "start": {
+              "column": 8,
+              "line": 1,
+              "offset": 7,
+            },
+          },
+          "loc": {
+            "end": {
+              "column": 27,
+              "line": 1,
+              "offset": 26,
+            },
+            "start": {
+              "column": 24,
+              "line": 1,
+              "offset": 23,
+            },
+          },
+          "name": "foo",
+        },
+      ]
+    `);
+  });
+
+  test('extracts multiple tokens from space-separated container-name', () => {
+    const decl = fakeDeclaration('.a_1 { container-name: foo bar }');
+    expect(parseContainerNameProp(decl).map((token) => token.name)).toMatchInlineSnapshot(`
+      [
+        "foo",
+        "bar",
+      ]
+    `);
+  });
+
+  test('omits reserved keywords from container-name', () => {
+    const decl = fakeDeclaration(
+      '.a_1 { container-name: none and not or inherit initial unset revert revert-layer default NONE }',
+    );
+    expect(parseContainerNameProp(decl)).toMatchInlineSnapshot(`[]`);
+  });
+
+  test('omits non-ident words from container-name', () => {
+    const decl = fakeDeclaration('.a_1 { container-name: 1foo }');
+    expect(parseContainerNameProp(decl)).toMatchInlineSnapshot(`[]`);
+  });
+});
+
+describe('parseContainerProp', () => {
+  test('extracts tokens before the slash from container shorthand', () => {
+    const decl = fakeDeclaration('.a_1 { container: foo bar / inline-size }');
+    expect(parseContainerProp(decl).map((token) => token.name)).toMatchInlineSnapshot(`
+      [
+        "foo",
+        "bar",
+      ]
+    `);
+  });
+
+  test('extracts tokens from container shorthand without a container-type', () => {
+    const decl = fakeDeclaration('.a_1 { container: foo bar }');
+    expect(parseContainerProp(decl).map((token) => token.name)).toMatchInlineSnapshot(`
+      [
+        "foo",
+        "bar",
+      ]
+    `);
+  });
+});
+
+describe('parseContainerAtRule', () => {
+  test('extracts a token reference from @container prelude', () => {
+    const atRule = fakeAtRule('@container foo (width > 400px) {}');
+    expect(parseContainerAtRule(atRule)).toMatchInlineSnapshot(`
+      {
+        "loc": {
+          "end": {
+            "column": 15,
+            "line": 1,
+            "offset": 14,
+          },
+          "start": {
+            "column": 12,
+            "line": 1,
+            "offset": 11,
+          },
+        },
+        "name": "foo",
+        "type": "local",
+      }
+    `);
+  });
+
+  test('omits reference when @container prelude has no name', () => {
+    const atRule = fakeAtRule('@container (width > 400px) {}');
+    expect(parseContainerAtRule(atRule)).toBeUndefined();
+  });
+
+  test('omits reference when @container prelude starts with a reserved keyword', () => {
+    const atRule = fakeAtRule('@container not (width > 400px) {}');
+    expect(parseContainerAtRule(atRule)).toBeUndefined();
+  });
+});
diff --git a/packages/core/src/parser/container-parser.ts b/packages/core/src/parser/container-parser.ts
new file mode 100644
index 00000000..a45a9d4d
--- /dev/null
+++ b/packages/core/src/parser/container-parser.ts
@@ -0,0 +1,94 @@
+import type { AtRule, Declaration } from 'postcss';
+import postcssValueParser from 'postcss-value-parser';
+import type { LocalTokenReference, Location, Token } from '../type.js';
+import { calcDeclValueLoc } from './util.js';
+import { VALID_IDENT_RE } from './util.js';
+
+export function isContainerNameProp(prop: string): boolean {
+  return prop.toLowerCase() === 'container-name';
+}
+
+export function isContainerProp(prop: string): boolean {
+  return prop.toLowerCase() === 'container';
+}
+
+export function isContainerAtRuleName(name: string): boolean {
+  return name.toLowerCase() === 'container';
+}
+
+/** Keywords that cannot be a `<container-name>`: the keywords excluded by `container-name`, the CSS-wide keywords, and `default`. */
+const CONTAINER_NAME_RESERVED_KEYWORDS = new Set([
+  // container-name
+  'none',
+  'and',
+  'not',
+  'or',
+  // CSS-wide keywords
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+  // reserved by <custom-ident>
+  'default',
+]);
+
+/** Parse a `container-name` declaration and extract a local token for each space-separated `<container-name>`. */
+export function parseContainerNameProp(decl: Declaration): Token[] {
+  return collectContainerNameTokens(decl, postcssValueParser(decl.value).nodes);
+}
+
+/** Parse a `container` shorthand declaration and extract local tokens from the `<container-name>` part before the `/`. */
+export function parseContainerProp(decl: Declaration): Token[] {
+  const nodes = postcssValueParser(decl.value).nodes;
+  const slashIndex = nodes.findIndex((node) => node.type === 'div' && node.value === '/');
+  const nameNodes = slashIndex === -1 ? nodes : nodes.slice(0, slashIndex);
+  return collectContainerNameTokens(decl, nameNodes);
+}
+
+function collectContainerNameTokens(decl: Declaration, nodes: postcssValueParser.Node[]): Token[] {
+  const tokens: Token[] = [];
+  const declarationLoc = calcDeclarationLoc(decl);
+  for (const node of nodes) {
+    if (node.type !== 'word') continue;
+    if (!isContainerName(node.value)) continue;
+    tokens.push({
+      name: node.value,
+      loc: calcDeclValueLoc(decl, node.sourceIndex, node.value.length),
+      declarationLoc,
+    });
+  }
+  return tokens;
+}
+
+function isContainerName(word: string): boolean {
+  if (CONTAINER_NAME_RESERVED_KEYWORDS.has(word.toLowerCase())) return false;
+  return VALID_IDENT_RE.test(word);
+}
+
+function calcDeclarationLoc(decl: Declaration): Location {
+  return {
+    start: decl.source!.start!,
+    end: decl.positionBy({ index: decl.toString().length }),
+  };
+}
+
+/**
+ * Parse an `@container` prelude and extract the leading `<container-name>` as a local token reference.
+ * @example `@container foo (width > 400px) {}` references the `foo` container.
+ */
+export function parseContainerAtRule(atRule: AtRule): LocalTokenReference | undefined {
+  const nameNode = postcssValueParser(atRule.params).nodes.find((node) => node.type !== 'space');
+  if (nameNode?.type !== 'word') return undefined;
+  if (!isContainerName(nameNode.value)) return undefined;
+
+  const startIndex = `@${atRule.name}${atRule.raws.afterName ?? ''}`.length + nameNode.sourceIndex;
+  return {
+    type: 'local',
+    name: nameNode.value,
+    loc: {
+      start: atRule.positionBy({ index: startIndex }),
+      end: atRule.positionBy({ index: startIndex + nameNode.value.length }),
+    },
+  };
+}
diff --git a/packages/core/src/parser/css-module-parser.test.ts b/packages/core/src/parser/css-module-parser.test.ts
index a78c016f..f9554c49 100644
--- a/packages/core/src/parser/css-module-parser.test.ts
+++ b/packages/core/src/parser/css-module-parser.test.ts
@@ -7,6 +7,7 @@ const options: ParseCSSModuleOptions = {
   includeSyntaxError: true,
   animation: true,
   dashedIdents: false,
+  container: false,
 };
 
 describe('parseCSSModule', () => {
@@ -997,4 +998,26 @@ describe('parseCSSModule', () => {
     expect(cssModule.localTokens.map((token) => token.name)).toStrictEqual(['a_1']);
     expect(cssModule.tokenReferences).toStrictEqual([]);
   });
+  test('collects container name tokens and references if container is true', () => {
+    const cssModule = parseCSSModule(
+      dedent`
+        .a_1 { container-name: foo; }
+        @container foo (width > 400px) {}
+      `,
+      { ...options, container: true },
+    );
+    expect(cssModule.localTokens.map((token) => token.name)).toStrictEqual(['a_1', 'foo']);
+    expect(cssModule.tokenReferences.map((ref) => ref.type === 'local' && ref.name)).toStrictEqual(['foo']);
+  });
+  test('does not collect container name tokens or references if container is false', () => {
+    const cssModule = parseCSSModule(
+      dedent`
+        .a_1 { container-name: foo; }
+        @container foo (width > 400px) {}
+      `,
+      { ...options, container: false },
+    );
+    expect(cssModule.localTokens.map((token) => token.name)).toStrictEqual(['a_1']);
+    expect(cssModule.tokenReferences).toStrictEqual([]);
+  });
 });
diff --git a/packages/core/src/parser/css-module-parser.ts b/packages/core/src/parser/css-module-parser.ts
index 72bc974e..a382b27a 100644
--- a/packages/core/src/parser/css-module-parser.ts
+++ b/packages/core/src/parser/css-module-parser.ts
@@ -20,6 +20,13 @@ import { parseValueAtRule } from './at-value-parser.js';
 import { isComposesProp, parseComposesProp } from './composes-parser.js';
 import {
   isContainerAtRuleName,
+  isContainerNameProp,
+  isContainerProp,
+  parseContainerAtRule,
+  parseContainerNameProp,
+  parseContainerProp,
+} from './container-parser.js';
+import {
   isDashedIdentAtRuleName,
   isMediaAtRuleName,
   parseDashedIdentAtRule,
@@ -57,7 +64,7 @@ function isDeclaration(node: Node): node is Declaration {
 /**
  * Collect tokens from the AST.
  */
-function collectTokens(ast: Root, animation: boolean, dashedIdents: boolean) {
+function collectTokens(ast: Root, animation: boolean, dashedIdents: boolean, container: boolean) {
   const allDiagnostics: DiagnosticWithDetachedLocation[] = [];
   const localTokens: Token[] = [];
   const tokenImporters: TokenImporter[] = [];
@@ -70,8 +77,12 @@ function collectTokens(ast: Root, animation: boolean, dashedIdents: boolean) {
         if (token) localTokens.push(token);
       } else if (dashedIdents && isMediaAtRuleName(node.name)) {
         tokenReferences.push(...parseDashedIdentMediaQuery(node));
-      } else if (dashedIdents && isContainerAtRuleName(node.name)) {
-        tokenReferences.push(...parseDashedIdentContainerQuery(node));
+      } else if (isContainerAtRuleName(node.name)) {
+        if (container) {
+          const reference = parseContainerAtRule(node);
+          if (reference) tokenReferences.push(reference);
+        }
+        if (dashedIdents) tokenReferences.push(...parseDashedIdentContainerQuery(node));
       } else if (isImportAtRuleName(node.name)) {
         const parsed = parseImportAtRule(node);
         if (parsed !== undefined) {
@@ -109,6 +120,10 @@ function collectTokens(ast: Root, animation: boolean, dashedIdents: boolean) {
         const { references, diagnostics } = parseAnimationProp(node);
         allDiagnostics.push(...diagnostics);
         tokenReferences.push(...references);
+      } else if (container && isContainerNameProp(node.prop)) {
+        localTokens.push(...parseContainerNameProp(node));
+      } else if (container && isContainerProp(node.prop)) {
+        localTokens.push(...parseContainerProp(node));
       } else if (isComposesProp(node.prop)) {
         tokenReferences.push(...parseComposesProp(node));
       } else if (dashedIdents) {
@@ -127,6 +142,7 @@ export interface ParseCSSModuleOptions {
   includeSyntaxError: boolean;
   animation: boolean;
   dashedIdents: boolean;
+  container: boolean;
 }
 /**
  * Parse CSS Module text.
@@ -134,7 +150,7 @@ export interface ParseCSSModuleOptions {
  */
 export function parseCSSModule(
   text: string,
-  { fileName, includeSyntaxError, animation, dashedIdents }: ParseCSSModuleOptions,
+  { fileName, includeSyntaxError, animation, dashedIdents, container }: ParseCSSModuleOptions,
 ): CSSModule {
   let ast: Root;
   const diagnosticFile = { fileName, text };
@@ -161,7 +177,12 @@ export function parseCSSModule(
     ast = safeParser(text, { from: fileName });
   }
 
-  const { localTokens, tokenImporters, tokenReferences, diagnostics } = collectTokens(ast, animation, dashedIdents);
+  const { localTokens, tokenImporters, tokenReferences, diagnostics } = collectTokens(
+    ast,
+    animation,
+    dashedIdents,
+    container,
+  );
   allDiagnostics.push(...diagnostics.map((diagnostic) => ({ ...diagnostic, file: diagnosticFile })));
   return {
     fileName,
diff --git a/packages/core/src/parser/dashed-ident-parser.ts b/packages/core/src/parser/dashed-ident-parser.ts
index 5d3324ca..7d0d8c49 100644
--- a/packages/core/src/parser/dashed-ident-parser.ts
+++ b/packages/core/src/parser/dashed-ident-parser.ts
@@ -93,10 +93,6 @@ export function isMediaAtRuleName(name: string): boolean {
   return name.toLowerCase() === 'media';
 }
 
-export function isContainerAtRuleName(name: string): boolean {
-  return name.toLowerCase() === 'container';
-}
-
 /**
  * Extract custom media references from an `@media` prelude, e.g. the `--foo` in
  * `@media (--foo) { ... }`, which references a `@custom-media --foo`. References nested
diff --git a/packages/core/src/parser/decl-value-location.ts b/packages/core/src/parser/util.ts
similarity index 65%
rename from packages/core/src/parser/decl-value-location.ts
rename to packages/core/src/parser/util.ts
index d49511f7..8c9c90a4 100644
--- a/packages/core/src/parser/decl-value-location.ts
+++ b/packages/core/src/parser/util.ts
@@ -14,3 +14,8 @@ export function calcDeclValueLoc(decl: Declaration, sourceIndex: number, length:
     end: decl.positionBy({ index: startIndex + length }),
   };
 }
+
+// A valid CSS identifier, including `<dashed-ident>`. Excludes `<time>` (`3s`), `<number>` (`2`),
+// and other non-ident words. We don't validate `hex digits`, because it is the job of linters.
+export const VALID_IDENT_RE =
+  /^-?([a-zA-Z\u0080-\uFFFF_]|(\\[^\r\n\f])|-(?![0-9]))((\\[^\r\n\f])|[a-zA-Z\u0080-\uFFFF_0-9-])*$/u;
diff --git a/packages/core/src/test/css-module.ts b/packages/core/src/test/css-module.ts
index 7b086104..4e894ad9 100644
--- a/packages/core/src/test/css-module.ts
+++ b/packages/core/src/test/css-module.ts
@@ -16,7 +16,7 @@ export function fakeCSSModule(args?: Partial<CSSModule>): CSSModule {
 
 export function readAndParseCSSModule(
   path: string,
-  options?: { animation?: boolean; dashedIdents?: boolean },
+  options?: { animation?: boolean; dashedIdents?: boolean; container?: boolean },
 ): CSSModule | undefined {
   let text: string;
   try {
@@ -29,5 +29,6 @@ export function readAndParseCSSModule(
     includeSyntaxError: false,
     animation: options?.animation ?? true,
     dashedIdents: options?.dashedIdents ?? false,
+    container: options?.container ?? false,
   });
 }
diff --git a/packages/core/src/test/faker.ts b/packages/core/src/test/faker.ts
index 00d07fac..a1b3cd19 100644
--- a/packages/core/src/test/faker.ts
+++ b/packages/core/src/test/faker.ts
@@ -13,6 +13,7 @@ export function fakeConfig(args?: Partial<CMKConfig>): CMKConfig {
     prioritizeNamedImports: false,
     animation: true,
     dashedIdents: false,
+    container: false,
     basePath: '/app',
     configFileName: '/app/tsconfig.json',
     compilerOptions: {},
diff --git a/packages/ts-plugin/src/language-plugin.ts b/packages/ts-plugin/src/language-plugin.ts
index 64308938..0d886e92 100644
--- a/packages/ts-plugin/src/language-plugin.ts
+++ b/packages/ts-plugin/src/language-plugin.ts
@@ -51,6 +51,7 @@ export function createCSSLanguagePlugin(
         includeSyntaxError: false,
         animation: config.animation,
         dashedIdents: config.dashedIdents,
+        container: config.container,
       });
       // oxlint-disable-next-line prefer-const
       let { text, mapping, linkedCodeMapping } = generateDts(cssModule, {
diff --git a/packages/vscode/schemas/tsconfig.schema.json b/packages/vscode/schemas/tsconfig.schema.json
index 52db1204..80d93c45 100644
--- a/packages/vscode/schemas/tsconfig.schema.json
+++ b/packages/vscode/schemas/tsconfig.schema.json
@@ -48,6 +48,12 @@
           "default": false,
           "title": "dashedIdents",
           "markdownDescription": "Determines whether to generate the [token](https://github.com/mizdra/css-modules-kit/blob/main/docs/glossary.md#token) of `<dashed-ident>`s (custom properties such as `--foo`) in the d.ts file."
+        },
+        "container": {
+          "type": "boolean",
+          "default": false,
+          "title": "container",
+          "markdownDescription": "Determines whether to generate the [token](https://github.com/mizdra/css-modules-kit/blob/main/docs/glossary.md#token) of container names (used in `container-name`, the `container` shorthand, and `@container`) in the d.ts file."
         }
       }
     }

From 98b2fdcb9db8b7c251f892d38352a86f003be9c6 Mon Sep 17 00:00:00 2001
From: mizdra <pp.mizdra@gmail.com>
Date: Sun, 5 Jul 2026 22:12:22 +0900
Subject: [PATCH 2/3] chore(examples): add usage example for
 `cmkOptions.container`

---
 examples/1-basic/generated/src/a.module.css.d.ts | 1 +
 examples/1-basic/src/a.module.css                | 6 ++++++
 examples/1-basic/src/a.tsx                       | 1 +
 examples/1-basic/tsconfig.json                   | 3 ++-
 4 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/examples/1-basic/generated/src/a.module.css.d.ts b/examples/1-basic/generated/src/a.module.css.d.ts
index 20cd02dc..c0e0f2ec 100644
--- a/examples/1-basic/generated/src/a.module.css.d.ts
+++ b/examples/1-basic/generated/src/a.module.css.d.ts
@@ -14,6 +14,7 @@ declare const styles = {
   '--anchor': '' as string,
   '--view-timeline': '' as string,
   '--scroll-timeline': '' as string,
+  'container': '' as string,
   ...blockErrorType((await import('./b.module.css')).default),
   'c_1': (await import('./c.module.css')).default['c_1'],
   'c_alias': (await import('./c.module.css')).default['c_2'],
diff --git a/examples/1-basic/src/a.module.css b/examples/1-basic/src/a.module.css
index fbf5e0a5..69448169 100644
--- a/examples/1-basic/src/a.module.css
+++ b/examples/1-basic/src/a.module.css
@@ -63,3 +63,9 @@
   scroll-timeline-name: --scroll-timeline;
   animation-timeline: --scroll-timeline;
 }
+
+/* container-name */
+:root {
+  container-name: container;
+}
+@container container (width > 400px) {}
diff --git a/examples/1-basic/src/a.tsx b/examples/1-basic/src/a.tsx
index a956d1fd..be2d5a43 100644
--- a/examples/1-basic/src/a.tsx
+++ b/examples/1-basic/src/a.tsx
@@ -11,6 +11,7 @@ styles['--position-try'];
 styles['--anchor'];
 styles['--view-timeline'];
 styles['--scroll-timeline'];
+styles['container'];
 styles.b_1;
 styles.b_2;
 styles.c_1;
diff --git a/examples/1-basic/tsconfig.json b/examples/1-basic/tsconfig.json
index f8a643f8..e7ef6fab 100644
--- a/examples/1-basic/tsconfig.json
+++ b/examples/1-basic/tsconfig.json
@@ -14,6 +14,7 @@
   },
   "cmkOptions": {
     "enabled": true,
-    "dashedIdents": true
+    "dashedIdents": true,
+    "container": true
   }
 }

From 7d329204669886c69d4e87dc0521c9d8d360bd0a Mon Sep 17 00:00:00 2001
From: mizdra <pp.mizdra@gmail.com>
Date: Sun, 5 Jul 2026 23:48:27 +0900
Subject: [PATCH 3/3] docs: describe why `cmkOptions.container` does not
 support `local()` and `global()`

---
 docs/design.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 docs/design.md

diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 00000000..b30fd09d
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,18 @@
+# Design Decisions
+
+This document records design decisions that are not obvious from the code, along with their rationale.
+
+## `cmkOptions.container` does not support `local(...)` / `global(...)`
+
+css-modules-kit does not interpret `local(...)` / `global(...)` in `container-name`, the `container` shorthand, or the `@container` prelude (e.g. `container-name: local(foo)`). Function nodes in these positions are ignored: they produce neither a token nor a token reference.
+
+Rationale:
+
+- The `cmkOptions.container` option follows the [`container` option of lightningcss's CSS Modules support](https://lightningcss.dev/css-modules.html#container-queries). lightningcss parses container names as plain `<custom-ident>`s and provides no `local(...)` / `global(...)` escape hatch.
+- css-loader does not scope container names at all. Therefore, no CSS Modules implementation gives `local(...)` in these positions any semantics.
+- Per [css-conditional-5](https://drafts.csswg.org/css-conditional-5/#container-name), the grammar of `container-name` is `none | <custom-ident>+`. Function forms are invalid CSS.
+- Extracting tokens from `local(...)` would emit names into the `.d.ts` that no bundler actually scopes.
+
+This is in contrast to constructs such as `animation-name`, the `animation` shorthand, and `@keyframes`, where css-modules-kit interprets escape hatches like `local(...)` / `global(...)` and `:local(...)` / `:global(...)` because css-loader implements that syntax for `<keyframes-name>`s.
+
+If lightningcss or css-loader adds an escape hatch for container names in the future, css-modules-kit should follow it.