feat(@poupe/tailwindcss): v0.6.0 - MD3 Expressive Shape System by amery · Pull Request #457 · poupe-ui/poupe

amery · 2025-06-29T15:10:25Z

@poupe/tailwindcss v0.6.0 - MD3 Expressive Shape System

Major release featuring a complete redesign of the Material Design 3 shape system with abbreviated semantic utilities, reducing CSS size from 71KB to ~6KB while adding support for multiple shape families and asymmetric corner control.

🎨 What's New

Abbreviated Semantic Shape System

Optimized implementation reducing CSS from 71KB to ~6KB
Clearer, more intuitive utility names balancing clarity with brevity
Default to rounded shapes (most common case)

Multiple Shape Families

Rounded (default): .shape-lg, .shape-xl
Squircle: iOS-style super-elliptical corners .shape-squircle-lg
Cut: Angled corners .shape-cut-sm
Concave: Inward curved corners (experimental)
Convex: Enhanced rounded corners with 1.5x multiplier

Asymmetric Corner Control

Individual corners: .shape-lg-tl, .shape-md-br
Grouped corners: .shape-lg-top, .shape-xl-left
Dynamic values: .shape-[20px], .shape-tl-[40px]

Enhanced Component Shapes

<button class="shape-button">MD3 Button</button>
<div class="shape-card">Card Content</div>
<button class="shape-fab">FAB</button>

💔 Breaking Changes

Shape Utility Naming

.shape-rounded-lg → .shape-lg
.shape-rounded-lg-t → .shape-lg-top
.shape-squircle → .shape-squircle-{scale}
.shape-top-square → .shape-{scale}-bottom

Shape Scale

Old scale names → New abbreviated names:

extra-small → xs
small → sm
medium → md
large → lg
extra-large → xl

Component shapes remain unchanged (e.g., .shape-button, .shape-card).

🚀 Migration Guide

<!-- Old -->
<div class="shape-rounded-large">...</div>
<div class="shape-rounded-large-t">...</div>
<div class="shape-squircle">...</div>

<!-- New -->
<div class="shape-lg">...</div>
<div class="shape-lg-top">...</div>
<div class="shape-squircle-lg">...</div>

📦 Installation

npm install @poupe/tailwindcss@0.6.0

🔧 Technical Improvements

Dedicated shape modules for better maintainability
Progressive enhancement with automatic fallbacks
Consistent CSS variable usage enabling runtime customization
Updated to TailwindCSS v4.1.11

📚 Documentation

Full documentation and examples available in:

✅ Testing

All tests passing (148 tests) with comprehensive coverage for the new shape system.

Summary by CodeRabbit

New Features
- Introduced a redesigned, compact, and semantically clear shape utility system, reducing CSS size from 71KB to ~6KB.
- Added new shape families: squircle, cut, concave, convex, and enhanced rounded shapes with size variants.
- Enabled fine-grained control with corner-specific and directional shape utilities.
- Added support for dynamic and arbitrary border-radius values using TailwindCSS v4 syntax.
- Provided new semantic component shape utilities and improved CSS variable customization.
Bug Fixes
- Improved browser compatibility for advanced shape utilities.
Documentation
- Updated and expanded documentation and migration guides to reflect the new shape system and utility naming conventions.
Chores
- Upgraded dependencies and refreshed development tools.
- Updated ESLint configuration for CSS baseline support.
Tests
- Revised and expanded tests to align with the new shape utility system.

coderabbitai · 2025-06-29T15:10:31Z

Walkthrough

This update introduces a comprehensive redesign of the shape system in the @poupe-tailwindcss package. The previous verbose and mask-image-based squircle utilities are replaced with a new, semantic, CSS variable-driven system that uses border-radius for shapes. The change adds new shape families, corner-specific utilities, dynamic value support, and updates all related documentation, tests, and configuration.

Changes

File(s)	Change Summary
`src/theme/shape-semantic.ts`, `src/theme/shape-match-utilities.ts`, `src/theme/shapes.ts`	Added new modules for semantic shape utilities, match-based utility generation, and shape constants/functions supporting the new system.
`src/theme/components.ts`	Removed previous shape logic and replaced with delegation to new semantic shape utilities.
`src/theme/plugin.ts`	Added dynamic shape utilities to the plugin function.
`src/theme/theme.ts`	Integrated semantic shape constants into theme constants.
`src/assets/default.css`, `src/assets/style.css`	Replaced old shape classes with new CSS variable-based border-radius utilities; added new shape families and corner-specific classes.
`src/theme/__tests__/components.test.ts`	Updated tests to reflect new utility structure and removed mask-image/squircle-specific checks.
`AGENT.md`, `README.md`	Rewrote documentation to describe the new, concise, semantic shape utility system, migration guide, and usage.
`CHANGELOG.md`	Documented the 0.6.0 release, detailing the shape system redesign, breaking changes, and technical improvements.
`eslint.config.mjs`	Added a rule for CSS baseline usage in CSS files.
`package.json`	Bumped version from 0.5.0 to 0.6.0.

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant TailwindCSS
  participant ShapeSemantic
  participant CSS

  Developer->>TailwindCSS: Uses new .shape-* utilities in markup
  TailwindCSS->>ShapeSemantic: Looks up utility class (e.g., .shape-lg, .shape-squircle-md)
  ShapeSemantic->>CSS: Generates border-radius (and variables) for requested shape
  CSS-->>Developer: Applies correct shape style via CSS variables

Possibly related PRs

poupe-ui/poupe#448: Introduced the initial MD3 shape system and squircle utilities; this PR is a direct redesign and extension of that system.

Suggested labels

enhancement, tailwindcss

Poem

In the garden of shapes, a rabbit hops with glee,
Out with the old, in with border-radius and glee!
Squircles and cuts, now easy to command,
With variables and corners, all shapes at hand.
CSS is lighter, the docs are bright—
Hop along, shapes, you fit just right!
🐇✨

✨ Finishing Touches

📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 2

🔭 Outside diff range comments (1)

packages/@poupe-tailwindcss/src/assets/default.css (1)
776-781: z-index: --value(...) is invalid in final CSS output

z-index expects an integer.
--value() is Tailwind’s author-time placeholder that should have been resolved by the plugin build step. Shipping it to the browser results in an illegal declaration that is simply dropped, so .scrim-* ends up with no stacking context at all.
-  z-index: --value(integer, [integer]);
+  /* plugin should have inlined the integer here – e.g. 950 */
+  z-index: var(--md-z-scrim-base); /* or a generated literal */
Please double-check the shape-/scrim utility generator so placeholders are replaced before writing default.css.

🧹 Nitpick comments (4)

packages/@poupe-tailwindcss/src/theme/shapes.ts (1)

274-294: Experimental concave implementation with appropriate warnings.

The function correctly warns users about its experimental status. Consider tracking the TODO for proper mask implementation.

Would you like me to create an issue to track the implementation of proper concave corner masks?
packages/@poupe-tailwindcss/src/assets/default.css (3)
849-856: Redundant utilities inflate bundle size

shape-none and shape-rounded-none are byte-identical except for two custom-property annotations that do not affect computed style for the default family (rounded). Keeping both multiplies the CSS by ~1 KiB when repeated across every corner variant.

If the generator always sets --md-shape-family, you can safely drop the plain shape-* variants or alias them via @apply, e.g.
-.shape-rounded-none { … }
+.shape-rounded-none { @apply shape-none; }
This shrinks the file considerably without functional loss.

1070-1082: Border-radius 14998.5px is excessive & harms rounding precision

The generator doubles the full radius (9999 px * 1.5) to obtain a “convex” look. Browsers clamp radii to the smallest of width/height, so anything above 9999px on most elements is equivalent to 9999px but harder to read and gzip-compress.

Recommend capping to 9999px (or simply 50%) for clarity:
-border-radius: var(--md-shape-full, 14998.5px);
+border-radius: var(--md-shape-full, 9999px); /* or 50% */
2921-2929: Missing shape-* alias utilities for new families

You added base aliases for shape-rounded, shape-squircle, etc., but not for recently introduced families (concave, convex, cut). Align with existing pattern for consistency & discoverability:
.shape-cut     { --md-shape-family: cut; }
.shape-concave { --md-shape-family: concave; }
.shape-convex  { --md-shape-family: convex; }

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1f410e7 and 2ef8ff2.

📒 Files selected for processing (10)

packages/@poupe-tailwindcss/AGENT.md (1 hunks)
packages/@poupe-tailwindcss/CHANGELOG.md (2 hunks)
packages/@poupe-tailwindcss/README.md (1 hunks)
packages/@poupe-tailwindcss/eslint.config.mjs (1 hunks)
packages/@poupe-tailwindcss/package.json (1 hunks)
packages/@poupe-tailwindcss/src/assets/default.css (13 hunks)
packages/@poupe-tailwindcss/src/assets/style.css (13 hunks)
packages/@poupe-tailwindcss/src/theme/__tests__/components.test.ts (2 hunks)
packages/@poupe-tailwindcss/src/theme/components.ts (3 hunks)
packages/@poupe-tailwindcss/src/theme/shapes.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (7)

`**/*.{js,ts,css,json}`: Use 2 spaces for indentation, Unix (LF) line endings, U...

**/*.{js,ts,css,json}: Use 2 spaces for indentation, Unix (LF) line endings, UTF-8 charset, single quotes for strings, always use semicolons, 1tbs (one true brace style), always use parentheses for arrow functions, max 78 characters preferred for line length, TSDoc format for documentation comments, ES modules (type: 'module'), camelCase for variables/functions, PascalCase for types/interfaces, always insert a final newline, and always trim trailing whitespace.

📄 Source: CodeRabbit Inference Engine (AGENT.md)

List of files the instruction was applied to:

packages/@poupe-tailwindcss/package.json
packages/@poupe-tailwindcss/src/theme/__tests__/components.test.ts
packages/@poupe-tailwindcss/src/theme/components.ts
packages/@poupe-tailwindcss/src/assets/default.css
packages/@poupe-tailwindcss/src/theme/shapes.ts
packages/@poupe-tailwindcss/src/assets/style.css

`**/*.{test.ts,spec.ts}`: Test files must be named with .test.ts or .spec.ts extensions.

**/*.{test.ts,spec.ts}: Test files must be named with .test.ts or .spec.ts extensions.

📄 Source: CodeRabbit Inference Engine (AGENT.md)

List of files the instruction was applied to:

packages/@poupe-tailwindcss/src/theme/__tests__/components.test.ts

`**/__tests__/**/*`: Test files may be located in __tests__ directories or colocated with source files.

**/__tests__/**/*: Test files may be located in tests directories or colocated with source files.

📄 Source: CodeRabbit Inference Engine (AGENT.md)

List of files the instruction was applied to:

packages/@poupe-tailwindcss/src/theme/__tests__/components.test.ts

`**/*.md`: For AGENT.md and README.md files, format lists with sub-bullets for m...

**/*.md: For AGENT.md and README.md files, format lists with sub-bullets for multi-item lists and dependencies, keep single-line descriptions and command descriptions on one line, be consistent with list item punctuation, add a blank line after section headings, and prefer 'with' over 'via' for relationships.

📄 Source: CodeRabbit Inference Engine (AGENT.md)

List of files the instruction was applied to:

packages/@poupe-tailwindcss/CHANGELOG.md
packages/@poupe-tailwindcss/README.md
packages/@poupe-tailwindcss/AGENT.md

`packages/@poupe-tailwindcss/AGENT.md`: Contains TailwindCSS integration details for the @poupe-tailwindcss package.

packages/@poupe-tailwindcss/AGENT.md: Contains TailwindCSS integration details for the @poupe-tailwindcss package.

📄 Source: CodeRabbit Inference Engine (AGENT.md)

List of files the instruction was applied to:

packages/@poupe-tailwindcss/AGENT.md

`packages/@poupe-tailwindcss/src/assets/default.css`: src/assets/default.css sho...

packages/@poupe-tailwindcss/src/assets/default.css: src/assets/default.css should be a complete example with Material Design 3 variables, full set of CSS custom properties, and all utilities with example theme colors, generated from build.config.ts.

📄 Source: CodeRabbit Inference Engine (packages/@poupe-tailwindcss/AGENT.md)

List of files the instruction was applied to:

packages/@poupe-tailwindcss/src/assets/default.css

`packages/@poupe-tailwindcss/src/assets/style.css`: src/assets/style.css should ...

packages/@poupe-tailwindcss/src/assets/style.css: src/assets/style.css should provide a minimal TailwindCSS v4 setup with surface utilities, shadow and elevation system, and scrim overlay utilities, but no theme colors.

📄 Source: CodeRabbit Inference Engine (packages/@poupe-tailwindcss/AGENT.md)

List of files the instruction was applied to:

packages/@poupe-tailwindcss/src/assets/style.css

🧠 Learnings (11)

📓 Common learnings

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The @poupe/theme-builder package provides a Material Design 2025 theme generation system, including design token generation, color extraction from images, theme variations, and runtime theme switching.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All Vue components in @poupe/vue must follow Material Design 3 guidelines, including semantic color tokens, tonal elevation, and dynamic color themes.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages must implement Material Design 3 principles: dynamic color system with theme tokens, tonal elevation, accessibility-first approach, responsive design, and consistent motion and interaction.

Learnt from: amery
PR: poupe-ui/poupe#412
File: packages/@poupe-theme-builder/package.json:3-3
Timestamp: 2025-05-30T15:45:43.757Z
Learning: The @poupe/theme-builder package version 0.9.x was considered beta/experimental. Breaking changes during the 0.9.x series don't require major version bumps since the API was still unstable. The transition from 0.9.1 to 0.9.2 represents stabilization of the theme-builder after the beta period.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages in the Poupe UI Framework monorepo must follow strict TypeScript practices, including explicit type annotations for union types and strict mode enabled.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: In the @poupe/css TypeScript utility library, provide type-safe support for CSS property names and values, ensuring that all utilities maintain type safety throughout.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The plugin supports configuration via tailwind.config.js, allowing customization of utility prefixes, color overrides, and surface utility generation.

Learnt from: amery
PR: poupe-ui/poupe#325
File: packages/@poupe-tailwindcss/src/flat/plugin.ts:7-7
Timestamp: 2025-05-07T20:52:45.565Z
Learning: The type definition `FlatOptions = unknown & {}` in `packages/@poupe-tailwindcss/src/flat/plugin.ts` is intentionally defined as a placeholder for future development.

packages/@poupe-tailwindcss/package.json (11)

Learnt from: amery
PR: poupe-ui/poupe#412
File: packages/@poupe-theme-builder/package.json:3-3
Timestamp: 2025-05-30T15:45:43.757Z
Learning: The @poupe/theme-builder package version 0.9.x was considered beta/experimental. Breaking changes during the 0.9.x series don't require major version bumps since the API was still unstable. The transition from 0.9.1 to 0.9.2 represents stabilization of the theme-builder after the beta period.

Learnt from: amery
PR: poupe-ui/poupe#426
File: packages/@poupe-tailwindcss/package.json:60-62
Timestamp: 2025-06-09T13:36:06.318Z
Learning: The `compile` utility in `packages/@poupe-tailwindcss/src/utils/compile.ts` is internal-only and not exported by `src/utils`, so dependencies it requires like `@tailwindcss/node` should remain in devDependencies rather than being moved to runtime dependencies.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The @poupe/theme-builder package provides a Material Design 2025 theme generation system, including design token generation, color extraction from images, theme variations, and runtime theme switching.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages in the Poupe UI Framework monorepo must follow strict TypeScript practices, including explicit type annotations for union types and strict mode enabled.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages are published independently to npm and must maintain backwards compatibility within major versions, following semantic versioning strictly.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: In the @poupe/css TypeScript utility library, provide type-safe support for CSS property names and values, ensuring that all utilities maintain type safety throughout.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The plugin supports configuration via tailwind.config.js, allowing customization of utility prefixes, color overrides, and surface utility generation.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: The theme system is built on @poupe/theme-builder, supporting reactive theme switching and CSS variable-based theming.

packages/@poupe-tailwindcss/eslint.config.mjs (11)

Learnt from: amery
PR: poupe-ui/poupe#426
File: packages/@poupe-tailwindcss/package.json:60-62
Timestamp: 2025-06-09T13:36:06.318Z
Learning: The `compile` utility in `packages/@poupe-tailwindcss/src/utils/compile.ts` is internal-only and not exported by `src/utils`, so dependencies it requires like `@tailwindcss/node` should remain in devDependencies rather than being moved to runtime dependencies.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: In the @poupe/css TypeScript utility library, provide type-safe support for CSS property names and values, ensuring that all utilities maintain type safety throughout.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages in the Poupe UI Framework monorepo must follow strict TypeScript practices, including explicit type annotations for union types and strict mode enabled.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: All example output CSS files (examples/*/output.css) are generated via the TailwindCSS CLI and are intended for human and browser testing, not for direct modification.

Learnt from: amery
PR: poupe-ui/poupe#47
File: package.json:16-17
Timestamp: 2024-12-02T02:55:16.072Z
Learning: ESLint version 9.x is in use and compatible with our codebase.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: CLI integration tests in src/__tests__/cli.test.ts validate that generated CSS assets and utilities work correctly with the actual TailwindCSS CLI, including modifier syntax and theme variable integration.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration is dynamically generated by `@poupe/theme-builder` in `tailwind.config.ts`, which makes the `shadow-shadow` class valid despite not being directly visible in the config files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: Implement both array-based and generator-based functions for formatting and generating CSS rules (e.g., formatCSSRules, generateCSSRules), where array functions are suitable for small to medium CSS and generator functions are preferred for memory-efficient handling of large CSS files.

packages/@poupe-tailwindcss/src/theme/__tests__/components.test.ts (11)

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: CLI integration tests in src/__tests__/cli.test.ts validate that generated CSS assets and utilities work correctly with the actual TailwindCSS CLI, including modifier syntax and theme variable integration.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.

Learnt from: amery
PR: poupe-ui/poupe#426
File: packages/@poupe-tailwindcss/package.json:60-62
Timestamp: 2025-06-09T13:36:06.318Z
Learning: The `compile` utility in `packages/@poupe-tailwindcss/src/utils/compile.ts` is internal-only and not exported by `src/utils`, so dependencies it requires like `@tailwindcss/node` should remain in devDependencies rather than being moved to runtime dependencies.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-nuxt/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:07.095Z
Learning: Test Nuxt modules for SSR compatibility, auto-import functionality, color mode integration, hydration correctness, and compatibility with different Nuxt configurations.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: In the @poupe/css TypeScript utility library, provide type-safe support for CSS property names and values, ensuring that all utilities maintain type safety throughout.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages in the Poupe UI Framework monorepo must follow strict TypeScript practices, including explicit type annotations for union types and strict mode enabled.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration is dynamically generated by `@poupe/theme-builder` in `tailwind.config.ts`, which makes the `shadow-shadow` class valid despite not being directly visible in the config files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: amery
PR: poupe-ui/poupe#116
File: packages/theme-builder/src/core.ts:87-90
Timestamp: 2025-01-12T11:29:26.546Z
Learning: In the theme-builder package, there are two different implementations of `rgbFromArgb()`:
1. In core.ts: Returns RGB values wrapped in `rgb()` for general CSS usage
2. In tailwind-common.ts: Returns space-separated RGB values without wrapper specifically for Tailwind CSS variables

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Components must export both default and typed props, using TypeScript's 'defineProps' with proper types.

packages/@poupe-tailwindcss/CHANGELOG.md (14)

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: amery
PR: poupe-ui/poupe#412
File: packages/@poupe-theme-builder/package.json:3-3
Timestamp: 2025-05-30T15:45:43.757Z
Learning: The @poupe/theme-builder package version 0.9.x was considered beta/experimental. Breaking changes during the 0.9.x series don't require major version bumps since the API was still unstable. The transition from 0.9.1 to 0.9.2 represents stabilization of the theme-builder after the beta period.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.

Learnt from: amery
PR: poupe-ui/poupe#426
File: packages/@poupe-tailwindcss/package.json:60-62
Timestamp: 2025-06-09T13:36:06.318Z
Learning: The `compile` utility in `packages/@poupe-tailwindcss/src/utils/compile.ts` is internal-only and not exported by `src/utils`, so dependencies it requires like `@tailwindcss/node` should remain in devDependencies rather than being moved to runtime dependencies.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The @poupe/theme-builder package provides a Material Design 2025 theme generation system, including design token generation, color extraction from images, theme variations, and runtime theme switching.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration is dynamically generated by `@poupe/theme-builder` in `tailwind.config.ts`, which makes the `shadow-shadow` class valid despite not being directly visible in the config files.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration comes from `MaterialDynamicColors.shadow` and is dynamically generated by `@poupe/theme-builder`. This makes classes like `shadow-shadow` valid despite not being directly visible in the Tailwind config files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages must implement Material Design 3 principles: dynamic color system with theme tokens, tonal elevation, accessibility-first approach, responsive design, and consistent motion and interaction.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: Design tokens are categorized into color tokens (with dim variants), state color tokens (with specific opacities for interactive states), typography tokens, shape tokens, motion tokens, and elevation tokens.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: The 'useRipple' composable handles Material Design ripple effects, including event handling, animation cleanup, and integration with the .ripple-effect utility.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All interactive components must support MD3 state layers, including hover, focus, pressed, and disabled states, with transitions using the '--md-state-transition-duration' CSS variable.

packages/@poupe-tailwindcss/README.md (15)

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: amery
PR: poupe-ui/poupe#412
File: packages/@poupe-theme-builder/package.json:3-3
Timestamp: 2025-05-30T15:45:43.757Z
Learning: The @poupe/theme-builder package version 0.9.x was considered beta/experimental. Breaking changes during the 0.9.x series don't require major version bumps since the API was still unstable. The transition from 0.9.1 to 0.9.2 represents stabilization of the theme-builder after the beta period.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All Vue components in @poupe/vue must follow Material Design 3 guidelines, including semantic color tokens, tonal elevation, and dynamic color themes.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The @poupe/theme-builder package provides a Material Design 2025 theme generation system, including design token generation, color extraction from images, theme variations, and runtime theme switching.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.

Learnt from: amery
PR: poupe-ui/poupe#426
File: packages/@poupe-tailwindcss/package.json:60-62
Timestamp: 2025-06-09T13:36:06.318Z
Learning: The `compile` utility in `packages/@poupe-tailwindcss/src/utils/compile.ts` is internal-only and not exported by `src/utils`, so dependencies it requires like `@tailwindcss/node` should remain in devDependencies rather than being moved to runtime dependencies.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration comes from `MaterialDynamicColors.shadow` and is dynamically generated by `@poupe/theme-builder`. This makes classes like `shadow-shadow` valid despite not being directly visible in the Tailwind config files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages must implement Material Design 3 principles: dynamic color system with theme tokens, tonal elevation, accessibility-first approach, responsive design, and consistent motion and interaction.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: Design tokens are categorized into color tokens (with dim variants), state color tokens (with specific opacities for interactive states), typography tokens, shape tokens, motion tokens, and elevation tokens.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All interactive components must support MD3 state layers, including hover, focus, pressed, and disabled states, with transitions using the '--md-state-transition-duration' CSS variable.

Learnt from: amery
PR: poupe-ui/poupe#388
File: packages/@poupe-tailwindcss/src/theme/theme.ts:321-329
Timestamp: 2025-05-26T00:23:51.659Z
Learning: In the shadow system implementation, the CSS Level 4 relative color syntax fallback (`from var(--shadow) r g b`) is intentional for edge cases. Users are expected to include the shadowRGB variable in their theme configuration to avoid hitting this fallback. The fallback is not the primary usage path.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Interactive surface utilities (e.g., .interactive-surface-*) automatically generate hover, focus, and pressed state layers with proper transitions, ensuring Material Design 3 state feedback is consistent and configurable.

packages/@poupe-tailwindcss/src/theme/components.ts (19)

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.

Learnt from: amery
PR: poupe-ui/poupe#426
File: packages/@poupe-tailwindcss/package.json:60-62
Timestamp: 2025-06-09T13:36:06.318Z
Learning: The `compile` utility in `packages/@poupe-tailwindcss/src/utils/compile.ts` is internal-only and not exported by `src/utils`, so dependencies it requires like `@tailwindcss/node` should remain in devDependencies rather than being moved to runtime dependencies.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: In the @poupe/css TypeScript utility library, provide type-safe support for CSS property names and values, ensuring that all utilities maintain type safety throughout.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration is dynamically generated by `@poupe/theme-builder` in `tailwind.config.ts`, which makes the `shadow-shadow` class valid despite not being directly visible in the config files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: CLI integration tests in src/__tests__/cli.test.ts validate that generated CSS assets and utilities work correctly with the actual TailwindCSS CLI, including modifier syntax and theme variable integration.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages in the Poupe UI Framework monorepo must follow strict TypeScript practices, including explicit type annotations for union types and strict mode enabled.

Learnt from: amery
PR: poupe-ui/poupe#116
File: packages/theme-builder/src/core.ts:87-90
Timestamp: 2025-01-12T11:29:26.546Z
Learning: In the theme-builder package, there are two different implementations of `rgbFromArgb()`:
1. In core.ts: Returns RGB values wrapped in `rgb()` for general CSS usage
2. In tailwind-common.ts: Returns space-separated RGB values without wrapper specifically for Tailwind CSS variables

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: All scrim utilities in @poupe/tailwindcss support opacity modifiers using the /[percentage] syntax (e.g., scrim-modal/50), and process these via CSS variables for flexible opacity control.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: Implement both array-based and generator-based functions for formatting and generating CSS rules (e.g., formatCSSRules, generateCSSRules), where array functions are suitable for small to medium CSS and generator functions are preferred for memory-efficient handling of large CSS files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: Utility functions should support parsing CSS property strings into structured data and formatting structured data back into CSS strings, including handling unit conversions and calculations.

Learnt from: amery
PR: poupe-ui/poupe#388
File: packages/@poupe-tailwindcss/src/theme/theme.ts:321-329
Timestamp: 2025-05-26T00:23:51.659Z
Learning: In the shadow system implementation, the CSS Level 4 relative color syntax fallback (`from var(--shadow) r g b`) is intentional for edge cases. Users are expected to include the shadowRGB variable in their theme configuration to avoid hitting this fallback. The fallback is not the primary usage path.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: Type safety for design tokens is ensured through TypeScript support.

Learnt from: amery
PR: poupe-ui/poupe#325
File: packages/@poupe-tailwindcss/src/flat/plugin.ts:7-7
Timestamp: 2025-05-07T20:52:45.565Z
Learning: The type definition `FlatOptions = unknown & {}` in `packages/@poupe-tailwindcss/src/flat/plugin.ts` is intentionally defined as a placeholder for future development.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Components must export both default and typed props, using TypeScript's 'defineProps' with proper types.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: Design tokens are categorized into color tokens (with dim variants), state color tokens (with specific opacities for interactive states), typography tokens, shape tokens, motion tokens, and elevation tokens.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The @poupe/theme-builder package provides a Material Design 2025 theme generation system, including design token generation, color extraction from images, theme variations, and runtime theme switching.

packages/@poupe-tailwindcss/AGENT.md (12)

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The @poupe/theme-builder package provides a Material Design 2025 theme generation system, including design token generation, color extraction from images, theme variations, and runtime theme switching.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: amery
PR: poupe-ui/poupe#412
File: packages/@poupe-theme-builder/package.json:3-3
Timestamp: 2025-05-30T15:45:43.757Z
Learning: The @poupe/theme-builder package version 0.9.x was considered beta/experimental. Breaking changes during the 0.9.x series don't require major version bumps since the API was still unstable. The transition from 0.9.1 to 0.9.2 represents stabilization of the theme-builder after the beta period.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All interactive components must support MD3 state layers, including hover, focus, pressed, and disabled states, with transitions using the '--md-state-transition-duration' CSS variable.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages must implement Material Design 3 principles: dynamic color system with theme tokens, tonal elevation, accessibility-first approach, responsive design, and consistent motion and interaction.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: Design tokens are categorized into color tokens (with dim variants), state color tokens (with specific opacities for interactive states), typography tokens, shape tokens, motion tokens, and elevation tokens.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All Vue components in @poupe/vue must follow Material Design 3 guidelines, including semantic color tokens, tonal elevation, and dynamic color themes.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Interactive surface utilities (e.g., .interactive-surface-*) automatically generate hover, focus, and pressed state layers with proper transitions, ensuring Material Design 3 state feedback is consistent and configurable.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration comes from `MaterialDynamicColors.shadow` and is dynamically generated by `@poupe/theme-builder`. This makes classes like `shadow-shadow` valid despite not being directly visible in the Tailwind config files.

packages/@poupe-tailwindcss/src/assets/default.css (13)

undefined

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: In the @poupe/css TypeScript utility library, provide type-safe support for CSS property names and values, ensuring that all utilities maintain type safety throughout.
</retrieved_learning>

<retrieved_learning>
Learnt from: amery
PR: #147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The shadow color in Tailwind configuration is dynamically generated by @poupe/theme-builder in tailwind.config.ts, which makes the shadow-shadow class valid despite not being directly visible in the config files.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.
</retrieved_learning>

<retrieved_learning>
Learnt from: amery
PR: #147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The shadow color in Tailwind configuration comes from MaterialDynamicColors.shadow and is dynamically generated by @poupe/theme-builder. This makes classes like shadow-shadow valid despite not being directly visible in the Tailwind config files.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: All scrim utilities in @poupe/tailwindcss support opacity modifiers using the /[percentage] syntax (e.g., scrim-modal/50), and process these via CSS variables for flexible opacity control.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: All example output CSS files (examples/*/output.css) are generated via the TailwindCSS CLI and are intended for human and browser testing, not for direct modification.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All interactive components must support MD3 state layers, including hover, focus, pressed, and disabled states, with transitions using the '--md-state-transition-duration' CSS variable.
</retrieved_learning>

<retrieved_learning>
Learnt from: amery
PR: #388
File: packages/@poupe-tailwindcss/src/theme/theme.ts:321-329
Timestamp: 2025-05-26T00:23:51.659Z
Learning: In the shadow system implementation, the CSS Level 4 relative color syntax fallback (from var(--shadow) r g b) is intentional for edge cases. Users are expected to include the shadowRGB variable in their theme configuration to avoid hitting this fallback. The fallback is not the primary usage path.
</retrieved_learning>

<retrieved_learning>
Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Interactive surface utilities (e.g., .interactive-surface-*) automatically generate hover, focus, and pressed state layers with proper transitions, ensuring Material Design 3 state feedback is consistent and configurable.
</retrieved_learning>

packages/@poupe-tailwindcss/src/theme/shapes.ts (17)

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: Material Design 3 shape utilities (e.g., .shape-none, .shape-medium, .shape-full) are extensible, use CSS variables for customization, and support squircle variants for smooth corners with SVG masks and graceful fallback.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: In the @poupe/css TypeScript utility library, provide type-safe support for CSS property names and values, ensuring that all utilities maintain type safety throughout.

Learnt from: amery
PR: poupe-ui/poupe#325
File: packages/@poupe-tailwindcss/src/flat/plugin.ts:7-7
Timestamp: 2025-05-07T20:52:45.565Z
Learning: The type definition `FlatOptions = unknown & {}` in `packages/@poupe-tailwindcss/src/flat/plugin.ts` is intentionally defined as a placeholder for future development.

Learnt from: amery
PR: poupe-ui/poupe#147
File: packages/poupe-vue/src/components/variants.ts:32-43
Timestamp: 2025-01-28T23:47:03.988Z
Learning: The `shadow` color in Tailwind configuration is dynamically generated by `@poupe/theme-builder` in `tailwind.config.ts`, which makes the `shadow-shadow` class valid despite not being directly visible in the config files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The @poupe/theme-builder package provides a Material Design 2025 theme generation system, including design token generation, color extraction from images, theme variations, and runtime theme switching.

Learnt from: CR
PR: poupe-ui/poupe#0
File: AGENT.md:0-0
Timestamp: 2025-06-28T22:46:55.639Z
Learning: All packages in the Poupe UI Framework monorepo must follow strict TypeScript practices, including explicit type annotations for union types and strict mode enabled.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-tailwindcss/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:22.143Z
Learning: The asMatchUtility function in src/theme/match-utilities.ts enables TailwindCSS v4 CSS syntax (using --value() and --modifier()) to be used with the v3 JavaScript matchUtilities API, supporting arbitrary values and modifiers for utilities like scrim overlays.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: TailwindCSS v4 with the @poupe/tailwindcss plugin is the required styling system; use the variant system for component variations and MD3 state layers.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Theme configuration is exported via '@poupe/vue/config' and integrates with @poupe/tailwindcss for consistent styling.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: The package is designed for integration with @poupe/vue (runtime theming), @poupe/tailwindcss (CSS generation), and @poupe/nuxt (SSR theme support).

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: Design tokens are categorized into color tokens (with dim variants), state color tokens (with specific opacities for interactive states), typography tokens, shape tokens, motion tokens, and elevation tokens.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-theme-builder/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:30.003Z
Learning: Type safety for design tokens is ensured through TypeScript support.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: Do not override Material Design principles without justification, skip accessibility requirements, or create components without proper TypeScript interfaces.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: Implement both array-based and generator-based functions for formatting and generating CSS rules (e.g., formatCSSRules, generateCSSRules), where array functions are suitable for small to medium CSS and generator functions are preferred for memory-efficient handling of large CSS files.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All interactive components must support MD3 state layers, including hover, focus, pressed, and disabled states, with transitions using the '--md-state-transition-duration' CSS variable.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-vue/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:37.659Z
Learning: All Vue components in @poupe/vue must follow Material Design 3 guidelines, including semantic color tokens, tonal elevation, and dynamic color themes.

Learnt from: CR
PR: poupe-ui/poupe#0
File: packages/@poupe-css/AGENT.md:0-0
Timestamp: 2025-06-28T22:47:00.833Z
Learning: Utility functions should support parsing CSS property strings into structured data and formatting structured data back into CSS strings, including handling unit conversions and calculations.

packages/@poupe-tailwindcss/src/assets/style.css (14)