EDU-15497 - CSS Analysis

[barbara-celi]

Types of changes

• New content (guides, endpoints, app documentation)
• Improvement (make a documentation even better)
• Fix (fix a documentation error)
• Spelling and grammar accuracy (self-explanatory)

EDU-15497

[github-actions]

Preview Links

Open this URL to set up the portal with this branch changes.

You can now access the edited pages with the following URLs:

• Couldn't find the corresponding page for docs/faststore/docs/faststore-analyzer/css-analysis.md. Have you added css-analysis to the navigation.json file? Maybe you can find it in https://developers.vtex.com/docs/guides/faststore/faststore-analyzer-css-analysis

[github-actions]

Navigation Preview Link

No changes detected in the navigation.json file

[github-actions]

Documentation feedback for docs/localization/css-analysis.md

Review of Explanation: CSS Analysis

Here's a breakdown of the feedback on the provided explanation, focusing on adherence to the given rules:

1. General Feedback

The explanation is generally well-structured and informative. It covers the key aspects of CSS analysis within the Analyzer tool. However, there are some areas where the content can be improved to better align with the provided guidelines, particularly regarding tone, heading case, and callout formatting.

2. Actionable Feedback

• R1.1 (Tone and Voice - Avoid unnecessary adverbs): The word "automatically" appears a few times. Consider if it's truly necessary or if the sentence works just as well without it.
• R13.1 (Headings - Sentence case): The heading "CSS Rules and enforcement" should be "CSS rules and enforcement".
• R12.1 & R12.2 (Callouts - Formatting): There are no callouts in the document, but consider adding some to highlight best practices or important warnings.

3. Suggested Revision

---
title:"CSS Analysis"
---

To enforce proper containment and prevent global style leakage, the Analyzer supports CSS analysis. As shown in [step 1](#instructions) of the previous section, when calling `analyzeFiles()`, you can specify CSS analysis options:

```typescript
await analyzer.analyzeFiles({
  filePattern: 'your-module/**/*.{js,ts,jsx,tsx,css,less,scss}',
  cssOptions: {
    allowedNamespaces: ['extension-'], // Array of allowed CSS namespace prefixes
    transformNonCompliant: true, // Whether to automatically fix non-compliant CSS
    defaultNamespace: 'extension-', // Default namespace to add to selectors
    verbose: true, // Output details and write transformed files to disk
    overwriteTransformed: true, // Whether to overwrite existing transformed files
  }
});

CSS rules and enforcement

The Analyzer checks for the following types of CSS violations:

• Global Selectors: Restricts usage of global selectors like *, body, html, :root which could affect the entire page.
• CSS Containment: Prevents CSS from breaking out of its intended containment and affecting other parts of the page.
• Namespace requirements: Ensures all selectors are properly namespaced (example: .extension-myClass instead of myClass) to avoid collisions.
• Restricted properties and values: Blocks usage of CSS properties and values that could compromise the sandbox integrity.
• Automatic transformation: When transformNonCompliant is enabled, the Analyzer attempts to fix CSS issues by:
  • Adding the default namespace to class and ID selectors.
  • Namespacing Keyframes animations.
  • Replacing global element selectors with namespaced container classes.
  • Adding containment properties to ensure styles don’t leak.
• Transformed files: When both transformNonCompliant and verbose are true, the Analyzer writes transformed CSS to files with .transformed.css extension, which can be used in your build process or debugging. Example:
  • Original: styles.css
  • Transformed: styles.transformed.css

Error handling

If violations are detected and transformNonCompliant is set to false, the Analyzer logs errors with detailed information. When transformNonCompliant is true, violations are fixed and logged as warnings.

The analysis output includes:

• Total number of files analyzed.
• List of violations by file, if any.
• List of warnings by file, if any.
• Paths to transformed CSS files, when applicable.

Best practices

⚠️ Avoid global selectors such as *, html, or body to prevent unintended style leakage.

ℹ️ Run CSS analysis during the pre-build stage to catch issues early.

• Early detection: Run CSS analysis during the pre-build stage to catch issues as early as possible.
• Namespace everything: Use your extension’s namespace prefix for all CSS selectors to avoid conflicts.
• Avoid global selectors: Don’t use universal * or document-level selectors like html, body, or :root.
• Enable transformation: Set transformNonCompliant: true in development to fix non-compliant styles.
• Review transformed CSS: Check the .transformed.css files to understand what was modified during the analysis.

<hr><h2 id="ai-feedback">Was this feedback useful?</h2>

- [ ] Yes
- [ ] No
<!-- thollander/actions-comment-pull-request "docs/localization/css-analysis.md" -->

[github-actions]

Frontmatter errors in docs/faststore/docs/faststore-analyzer/css-analysis.md:

• Frontmatter in 'docs/faststore/docs/faststore-analyzer/css-analysis.md' is not a valid YAML dictionary.
• Missing required field: 'title'.

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Total number of files analyz..."]

[github-actions]

[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

	- Total number of files analyzed.
	- Total number of files analyzed.

[github-actions]

[link-check] _{reported by reviewdog 🐶}
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/faststore/faststore-analyzer-implementation#instructions

👉 Please review this link before merging your Pull Request.