packages/theme/src/theme-tool.d.ts (1)

2-7: Consider adding English translations to property documentation.

While the new properties are well-structured, consider adding English translations to the JSDoc comments to maintain consistency with international development practices. This would improve accessibility for non-Chinese speaking developers.

-  /** 主题的ID */
+  /** Theme ID (主题的ID) */
   id?: string
-  /** 主题的名称 */
+  /** Theme name (主题的名称) */
   name?: string
-  /** 主题的中文名称 */
+  /** Theme Chinese name (主题的中文名称) */
   cnName?: string

examples/sites/src/assets/custom-block.less (2)

1-4: Consider simplifying selector specificity.

The double .markdown-body class selector (.markdown-body.markdown-body) seems unnecessary and could lead to specificity issues. A single class should be sufficient unless there's a specific reason for the increased specificity.

-.markdown-body.markdown-body ul,
-.markdown-body.markdown-body ol,
-.markdown-body.markdown-body li {
+.markdown-body ul,
+.markdown-body ol,
+.markdown-body li {
   list-style: disc;
}

---

41-41: Consider optimizing line height for readability.

The current line height of 30px with a 14px font size results in a relatively large spacing ratio (~2.14). Consider reducing it to improve readability of dense documentation.

-    line-height: 30px;
+    line-height: 1.6;

This change:

• Uses a relative value instead of fixed pixels
• Provides better readability with a more standard ratio
• Maintains consistency across different font sizes

examples/sites/demos/pc/webdoc/theme.md (3)

21-38: Consider enhancing the ThemeData interface documentation.

While the interface is well-documented, consider adding:

• Validation requirements for the id field (allowed characters, length)
• Format requirements for the css property (valid CSS syntax)
• Examples of valid data property values

---

43-69: Consider adding CSS specificity guidelines.

The example demonstrates theme customization well, but consider adding a note about CSS specificity when overriding styles, particularly for the .tiny-button selectors.

---

114-116: Enhance migration guidance for old themes.

Consider adding:

• Specific steps for migrating from old themes to new themes
• Common issues that might arise during migration
• A troubleshooting guide for theme-related problems

examples/sites/demos/pc/webdoc/theme-en.md (4)

1-14: LGTM! Consider adding examples of global CSS variables.

The introduction and version compatibility notice are clear and well-structured. The links to source files are helpful for users who want to explore the CSS variables.

Consider adding a few common examples of global CSS variables (like colors or spacing) to give users a quick reference without having to navigate to the source files.

---

80-102: Consider adding error handling examples for micro frontends.

While the micro frontends section provides good guidance, it would be beneficial to include error handling examples for cases where the ShadowRoot might not be immediately available.

Add error handling example:

 const wujieDom = document.querySelector('wujie-app[data-wujie-id]')
+if (!wujieDom) {
+  console.warn('Wujie app container not found')
+  return
+}
 const target = wujieDom.shadowRoot
+if (!target) {
+  console.warn('ShadowRoot not available')
+  return
+}

---

Line range hint 120-231: Improve organization of historical documentation.

The historical version configuration section needs better organization:

1. Some content is in Chinese while the document is primarily in English
2. Code examples use inconsistent formatting
3. The section could benefit from clearer version compatibility headers

Consider restructuring this section to:

1. Clearly mark it as legacy documentation
2. Maintain consistent language (English)
3. Use consistent code formatting
4. Add version compatibility notes at the start of each subsection

---

Line range hint 231-275: Enhance readability of special cases documentation.

While the variable standardization section is comprehensive, the special cases could be presented in a more structured format.

Consider using a table format for the special cases:

| Old Variable Pattern | New Variables | Example |
|---------------------|---------------|---------|
| *-padding | *-padding-vertical, *-padding-horizontal | `--ti-button-padding` → `--ti-button-padding-vertical`, `--ti-button-padding-horizontal` |
| *-primary-color | *-primary-bg-color, *-primary-text-color, *-primary-border-color | `--ti-pager-primary-color` → `--ti-pager-primary-bg-color`, etc. |

Configuration used: CodeRabbit UI
Review profile: CHILL

examples/sites/demos/pc/webdoc/theme.md (3)

20-39: Consider adding validation examples for ThemeData properties.

While the interface is well-documented, it would be helpful to include:

• Example validation for color values in data property
• Sample regex patterns for valid CSS in the css property
• Common pitfalls to avoid

---

43-69: Consider documenting CSS specificity guidelines.

The example demonstrates theme customization well. Consider adding:

• Notes about CSS specificity when overriding styles
• Guidelines for when to use global variables vs component-specific styles
• Best practices for managing style conflicts

---

114-116: Consider adding specific upgrade guidance.

While the warning is clear, consider adding:

• Common issues encountered during upgrades
• Step-by-step migration guide from old to new theme
• Compatibility matrix showing which features might break

Configuration used: CodeRabbit UI
Review profile: CHILL

examples/sites/demos/pc/webdoc/theme.md (3)

3-7: Enhance version compatibility information.

Consider adding:

• Release date of version 3.19.0
• Migration guide link for users on older versions
• Table comparing features between old and new theme systems

---

22-41: Add comprehensive examples for ThemeData interface.

Consider enhancing the interface documentation with:

• Complete example showing all properties in use
• Common use cases for each property
• Validation rules or constraints for each field

---

104-118: Add version compatibility matrix for OLD theme configuration.

To help users make informed decisions, consider adding:

• Version compatibility matrix
• Known issues with each version
• Timeline for OLD theme support end-of-life

Configuration used: CodeRabbit UI
Review profile: CHILL

packages/theme/src/theme-tool.js (2)

Line range hint 6-38: Enhance documentation and type safety.

While the implementation is solid, consider the following improvements:

1. Add JSDoc documentation for the class and methods
2. Add type annotations for parameters
3. Add validation for theme data structure

Here's a suggested improvement:

 /**
- * 动态切换文档或影子根节点的样式类
+ * A utility class for dynamically switching styles in documents or shadow roots.
+ * @class
+ * @classdesc Manages theme switching by manipulating CSS custom properties and stylesheets.
  */
 export default class TinyThemeTool {
+  /**
+   * @typedef {Object} Theme
+   * @property {Record<string, string>} [data] - CSS custom properties key-value pairs
+   * @property {string} [css] - Additional CSS rules
+   */
+
+  /**
+   * @param {Theme} [theme] - Initial theme configuration
+   */
   constructor(theme) {
     this.loaded = {} // Cache loaded styles
     if (theme) {
       this.changeTheme(theme)
     }
   }

+  /**
+   * Changes the theme by updating CSS custom properties and styles
+   * @param {Theme} theme - Theme configuration
+   * @param {Document|ShadowRoot} [target=document] - Target document or shadow root
+   * @throws {Error} If theme data is invalid
+   */
   changeTheme(theme, target = document) {
+    if (theme && typeof theme !== 'object') {
+      throw new Error('Theme must be an object')
+    }
+
     let loadedSheet = this.loaded[target]

---

Line range hint 24-38: Add error handling for theme data processing.

The theme data processing could benefit from additional validation and error handling.

Consider adding these safety checks:

     if (theme && (theme.data || theme.css)) {
       let cssContent = ''
       if (theme.data && typeof theme.data === 'object') {
+        // Validate CSS custom property names
+        const invalidKeys = Object.keys(theme.data).filter(key => !/^[a-zA-Z0-9-_]+$/.test(key))
+        if (invalidKeys.length > 0) {
+          throw new Error(`Invalid CSS custom property names: ${invalidKeys.join(', ')}`)
+        }
+
         cssContent = Object.keys(theme.data)
           .map((key) => `--${key}: ${theme.data[key]}; `)
           .join('')

         cssContent = `:root{${cssContent}}`
       }
       if (theme.css && typeof theme.css === 'string') {
+        // Basic CSS injection safety check
+        if (theme.css.includes('</style>')) {
+          throw new Error('Potential CSS injection detected')
+        }
         cssContent += theme.css
       }

       loadedSheet.replaceSync(cssContent)
     }

examples/sites/demos/pc/webdoc/theme.md (2)

3-14: Consider adding migration guidance for users upgrading from older versions.

While the version requirements and style changes are well documented, consider adding:

• Step-by-step migration guide
• Common pitfalls during upgrade
• Compatibility matrix showing which features work with which versions

---

22-41: Consider documenting ThemeData validation rules.

The interface properties are well documented, but consider adding:

• Valid value ranges/formats for each property
• Required vs optional properties
• Examples of valid and invalid values

Configuration used: CodeRabbit UI
Review profile: CHILL