>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2404111. --> Reported by: [jhodgdon](https://www.drupal.org/user/155601) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>On <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2293627" title="Status: Closed (duplicate)">#2293627: [meta] Document Human Interface Guidelines and make Seven style guide</a></span>, there was a discussion of making a Seven theme visual style guide, and it got mixed up into a discussion of making a better Human Interface Guidelines (HIG) document. On comment #42 &amp; #43, we decided these two goals were not really the same, and that we needed to start over with two new issues. This one is about the Seven Style Guide. See <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/drupal/issues/2404109" title="Status: Active">#2404109: [meta] Update and improve linking to Human Interface Guidelines docs</a></span> for the HIG.</p> <h4>Audience goals</h4> <p><strong>Module developers,</strong> who seek to understand how to build an admin interface for their module that is consistent with the existing admin interface.</p> <p><strong>Contrib admin theme maintainers,</strong> who seek to understand which UI components they need to support and override in order to support core and contrib Drupal modules. (See: <a href="https://groups.drupal.org/node/454113">Changes to Drupal 8 that affect admin theme maintainers</a>)</p> <h4>Previous attempts at documenting the Seven Style Guide and their pitfalls</h4> <p><a href="https://groups.drupal.org/node/283223">Proposal: A Style Guide for Seven</a> &mdash; Static images and text maintained on g.d.o. Does not evolve alongside development in core, quickly became out of date with the evolving style guide. Content is managed elsewhere, so it's easy to forget to update it. Static images are not a great way to display designs, due to lack of browser and viewport context.</p> <p><a href="http://cgit.drupalcode.org/sandbox-ry5n-1932040/plain/index.html?id=HEAD">Seventy eight sandbox</a> &mdash; Documented components in HTML + CSS, built on a style guide framework that allows you to view the components at different viewport sizes and browsers. Also out of date with core, as the content and styling is managed elsewhere.</p> <p>We also had a design test module in Drupal 8 that was unused <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2037569" title="Status: Closed (fixed)">#2037569: Remove design_test module</a></span></p> <h4>Current proposal requirements based on previous efforts</h4> <ul> <li>Must stay up to date the evolution of the implementation in core</li> <li>Must display how the context of the browser and viewport affect the display of components</li> <li>Must be difficult to "forget" to update the style guide content when required</li> </ul> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <h4>Build a guide using KSS</h4> <p>We explored some possible solutions in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2102191" title="Status: Closed (fixed)">#2102191: Discuss the availiable solutions to document the Seven style guide</a></span>. We propose the following:</p> <p><strong>1. Use inline CSS comments</strong></p> <ul> <li>They mimic the same placement as Drupal's PHP functions.</li> <li>The are tied directly to the code, so if the CSS is updated it's easy to update the documentation if need be</li> <li>They are not tied to a specific display, which means any site that checks out the D8 repo can parse the comments and generate documentation. This allows us to find the best solution for the documentation display over time without modifying the core repo. We could expand api.drupal.org or create a new site like <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/lost_and_found_issues/issues/2235485" title="Status: Active">#2235485: [meta] Automated Theme Component Library - Overall concept/discussion</a></span> or use a completely separate site</li> <li>It follows a similar approach to api.drupal.org, using comments in code</li> </ul> <p><strong>2. Use a CSS document syntax parser</strong><br> We propose following the same modal as for API.Drupal.org by having a document syntax parser. We will follow the relevant guidelines that are set in <a href="https://www.drupal.org/coding-standards/docs#general">API documentation and comment standards</a>. However we will need to append these guidelines with some specific style guide tags to allow for appropriate styling in the website. </p> <p><strong>3. Provide a website that provides the pattern library</strong><br> We propose using the KSS document syntax parser. This provides us with the HTML structure to build a website, following common user interface library patterns of grouping similar patterns. This means that the pattern library will be auto-generated and auto-updated following the information architecture and styling that we wish. Without having to hinder other parts of our documentation. </p> <blockquote><p>KSS attempts to provide a methodology for writing maintainable, documented CSS within a team. Specifically, KSS is a documentation specification and styleguide format. It is not a preprocessor, CSS framework, naming convention, or specificity guideline.</p></blockquote> <p>The full specification of KSS can be read at <a href="https://github.com/kneath/kss/blob/master/SPEC.md">Spec on GitHub</a>. The KSS framework is used by several other organisations and has a Node.JS or PHP implementation. </p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ol> <li><del><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2033211" title="Status: Closed (fixed)">#2033211: Move Seven CSS files into css directory</a></span></del></li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2321505" title="Status: Closed (fixed)">#2321505: Split Seven's style.css into SMACSS categories</a></span></li> <li>Add CSS documentation to each one: <ol> <li>Layout - <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2349897" title="Status: Closed (won't fix)">#2349897: Document layout.css with CSS comments</a></span></li> <li>Icons</li> <li>Typography - <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/seven/-/work_items/2349913" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/seven/-/work_items/2349913</a></span> <ol> <li>Headers</li> <li>Paragraphs</li> </ol> </li> <li>Tables - <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/seven/-/work_items/2349917" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/seven/-/work_items/2349917</a></span></li> <li>Form Inputs - <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2349919" title="Status: Closed (won't fix)">#2349919: Document form.css with CSS comments</a></span></li> <li>Buttons - <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/seven/-/work_items/2335009" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/seven/-/work_items/2335009</a></span></li> <li>Dropbuttons - <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2349921" title="Status: Closed (won't fix)">#2349921: Document dropbutton.component.css with CSS comments</a></span></li> <li>Tabs - <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2349947" title="Status: Closed (won't fix)">#2349947: Document tabs.css with CSS comments</a></span> <ol> <li>Primary tabs</li> <li>Secondary tabs</li> <li>Vertical tabs</li> </ol> </li> <li>Breadcrumbs - <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2349953" title="Status: Closed (won't fix)">#2349953: Document breadcrumb.css with CSS comments</a></span></li> <li>Pagination - <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2349959" title="Status: Closed (won't fix)">#2349959: Document pager.css with CSS comments</a></span></li> <li>Content header</li> <li>Modal dialog - <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2349927" title="Status: Closed (won't fix)">#2349927: Document dialog.theme.css with CSS comments</a></span></li> </ol> </li> </ol> <h4 id="beta-evaluation">Beta phase evaluation</h4> <p>This applies to child issues. Copy and paste...</p> <!--Uncomment the relevant rows for the issue. --><table> <caption>Reference: <a href="https://www.drupal.org/core/beta-changes">https://www.drupal.org/core/beta-changes</a></caption> <tr> <th><a href="https://www.drupal.org/core/issue-category">Issue category</a></th> <td>Task because it's adding new documentation</td> </tr> <tr> <th><a href="https://www.drupal.org/core/issue-priority">Issue priority</a></th> <td>Normal priority</td> </tr> <tr> <th><a href="https://www.drupal.org/core/beta-changes#unfrozen">Unfrozen changes</a></th> <td>Unfrozen because it only changes documentation.</td> </tr> <!--<tr><th><a href="https://www.drupal.org/core/beta-changes#prioritized">Prioritized changes</a></th><td>The main goal of this issue is usability/accessibility/security/performance/removing previously deprecated code/Migrate. / This is not a prioritized change for the beta phase.</td></tr>--><!--<tr><th><a href="https://www.drupal.org/core/beta-changes#disruption">Disruption</a></th> <td>Disruptive for core/contributed and custom modules/themes because it will require a BC break/deprecation/internal refactoring/widespread changes...</td></tr>--></table> <h3>Follow up improvements</h3> <ol> <li>Provide the documentation closer to the methods.</li> <li>Provide references to the relevant templates, to allow direct linking.</li> </ol> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> > Related issue: [Issue #2404109](https://www.drupal.org/node/2404109) > Related issue: [Issue #2235485](https://www.drupal.org/node/2235485) > Related issue: [Issue #2447835](https://www.drupal.org/node/2447835) > Related issue: [Issue #2293627](https://www.drupal.org/node/2293627)