A place to cache linked articles (think custom and personal wayback machine)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
  1. title: SUIT CSS naming conventions
  2. url: https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md
  3. hash_url: 40b989f3f54a5df59c66a2ad36b7861c
  4. <p>SUIT CSS relies on <em>structured class names</em> and <em>meaningful hyphens</em> (i.e., not
  5. using hyphens merely to separate words). This helps to work around the current
  6. limits of applying CSS to the DOM (i.e., the lack of style encapsulation), and
  7. to better communicate the relationships between classes.</p>
  8. <p>The primary architectural division is between <strong><a href="https://github.com/suitcss/suit/blob/master/doc/utilities.md">utilities</a></strong> and
  9. <strong><a href="https://github.com/suitcss/suit/blob/master/doc/components.md">components</a></strong>.</p>
  10. <p>Low-level structural and positional traits. Utilities can be applied directly
  11. to any element within a component.</p>
  12. <p>Syntax: <code>u-[sm|md|lg-]&lt;utilityName&gt;</code></p>
  13. <h3>
  14. <a id="user-content-u-utilityname" class="anchor" href="#u-utilityname" aria-hidden="true"><span class="octicon octicon-link"/></a>u-utilityName</h3>
  15. <p>Utilities must use a camel case name. What follows is an example of how various
  16. utilities can be used to create a simple structure within a component.</p>
  17. <div class="highlight highlight-html"><pre>&lt;<span class="pl-ent">div</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>u-cf<span class="pl-pds">"</span></span>&gt;
  18. &lt;<span class="pl-ent">a</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>u-floatLeft<span class="pl-pds">"</span></span> <span class="pl-e">href</span>=<span class="pl-s"><span class="pl-pds">"</span>{{url}}<span class="pl-pds">"</span></span>&gt;
  19. &lt;<span class="pl-ent">img</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>u-block<span class="pl-pds">"</span></span> <span class="pl-e">src</span>=<span class="pl-s"><span class="pl-pds">"</span>{{src}}<span class="pl-pds">"</span></span> <span class="pl-e">alt</span>=<span class="pl-s"><span class="pl-pds">"</span><span class="pl-pds">"</span></span>&gt;
  20. &lt;/<span class="pl-ent">a</span>&gt;
  21. &lt;<span class="pl-ent">p</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>u-sizeFill u-textBreak<span class="pl-pds">"</span></span>&gt;
  22. &lt;/<span class="pl-ent">p</span>&gt;
  23. &lt;/<span class="pl-ent">div</span>&gt;</pre></div>
  24. <h3>
  25. <a id="user-content-responsive-utilities" class="anchor" href="#responsive-utilities" aria-hidden="true"><span class="octicon octicon-link"/></a>Responsive utilities</h3>
  26. <p>Certain utilities have responsive variants using the patterns: <code>u-sm-&lt;name&gt;</code>,
  27. <code>u-md-&lt;name&gt;</code>, and <code>u-lg-&lt;name&gt;</code> for small, medium, and large Media Query
  28. breakpoints.</p>
  29. <p>The CSS responsible for component-specific styling.</p>
  30. <p>Syntax: <code>[&lt;namespace&gt;-]&lt;ComponentName&gt;[--modifierName|-descendentName]</code></p>
  31. <p>This has several benefits when reading and writing HTML and CSS:</p>
  32. <ul class="task-list">
  33. <li>It helps to distinguish between the classes for the root of the component,
  34. descendent elements, and modifications.</li>
  35. <li>It keeps the specificity of selectors low.</li>
  36. <li>It helps to decouple presentation semantics from document semantics.</li>
  37. </ul>
  38. <h3>
  39. <a id="user-content-namespace-optional" class="anchor" href="#namespace-optional" aria-hidden="true"><span class="octicon octicon-link"/></a>namespace (optional)</h3>
  40. <p>If necessary, components can be prefixed with a namespace. For example, you may
  41. wish to avoid the potential for collisions between libraries and your custom
  42. components by prefixing all your components with a namespace.</p>
  43. <div class="highlight highlight-css"><pre><span class="pl-e">.twt-Button</span> { <span class="pl-c">/* … */</span> }
  44. <span class="pl-e">.twt-Tabs</span> { <span class="pl-c">/* … */</span> }</pre></div>
  45. <p>This makes it clear, when reading the HTML, which components are part of your
  46. library.</p>
  47. <h3>
  48. <a id="user-content-componentname" class="anchor" href="#componentname" aria-hidden="true"><span class="octicon octicon-link"/></a>ComponentName</h3>
  49. <p>The component's name must be written in pascal case. Nothing else in the
  50. HTML/CSS uses pascal case.</p>
  51. <div class="highlight highlight-html"><pre>&lt;<span class="pl-ent">article</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>MyComponent<span class="pl-pds">"</span></span>&gt;
  52. &lt;/<span class="pl-ent">article</span>&gt;</pre></div>
  53. <h3>
  54. <a id="user-content-componentname--modifiername" class="anchor" href="#componentname--modifiername" aria-hidden="true"><span class="octicon octicon-link"/></a>ComponentName--modifierName</h3>
  55. <p>A component modifier is a class that modifies the presentation of the base
  56. component in some form (e.g., for a certain configuration of the component).
  57. Modifier names must be written in camel case and be separated from the
  58. component name by two hyphens. The class should be included in the HTML <em>in
  59. addition</em> to the base component class.</p>
  60. <div class="highlight highlight-css"><pre><span class="pl-c">/* Core button */</span>
  61. <span class="pl-e">.Button</span> { <span class="pl-c">/* … */</span> }
  62. <span class="pl-c">/* Default button style */</span>
  63. <span class="pl-e">.Button--default</span> { <span class="pl-c">/* … */</span> }</pre></div>
  64. <div class="highlight highlight-html"><pre>&lt;<span class="pl-ent">button</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>Button Button--default<span class="pl-pds">"</span></span> <span class="pl-e">type</span>=<span class="pl-s"><span class="pl-pds">"</span>button<span class="pl-pds">"</span></span>&gt;…&lt;/<span class="pl-ent">button</span>&gt;</pre></div>
  65. <h3>
  66. <a id="user-content-componentname-descendentname" class="anchor" href="#componentname-descendentname" aria-hidden="true"><span class="octicon octicon-link"/></a>ComponentName-descendentName</h3>
  67. <p>A component descendent is a class that is attached to a descendent node of a
  68. component. It's responsible for applying presentation directly to the
  69. descendent on behalf of a particular component. Descendent names must be
  70. written in camel case.</p>
  71. <div class="highlight highlight-html"><pre>&lt;<span class="pl-ent">article</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>Tweet<span class="pl-pds">"</span></span>&gt;
  72. &lt;<span class="pl-ent">header</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>Tweet-header<span class="pl-pds">"</span></span>&gt;
  73. &lt;<span class="pl-ent">img</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>Tweet-avatar<span class="pl-pds">"</span></span> <span class="pl-e">src</span>=<span class="pl-s"><span class="pl-pds">"</span>{{src}}<span class="pl-pds">"</span></span> <span class="pl-e">alt</span>=<span class="pl-s"><span class="pl-pds">"</span>{{alt}}<span class="pl-pds">"</span></span>&gt;
  74. &lt;/<span class="pl-ent">header</span>&gt;
  75. &lt;<span class="pl-ent">div</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>Tweet-bodyText<span class="pl-pds">"</span></span>&gt;
  76. &lt;/<span class="pl-ent">div</span>&gt;
  77. &lt;/<span class="pl-ent">article</span>&gt;</pre></div>
  78. <h3>
  79. <a id="user-content-componentnameis-stateofcomponent" class="anchor" href="#componentnameis-stateofcomponent" aria-hidden="true"><span class="octicon octicon-link"/></a>ComponentName.is-stateOfComponent</h3>
  80. <p>Use <code>is-stateName</code> to reflect changes to a component's state. The state name
  81. must be camel case. <strong>Never style these classes directly; they should always be
  82. used as an adjoining class.</strong></p>
  83. <p>This means that the same state names can be used in multiple contexts, but
  84. every component must define its own styles for the state (as they are scoped to
  85. the component).</p>
  86. <div class="highlight highlight-css"><pre><span class="pl-e">.Tweet</span> { <span class="pl-c">/* … */</span> }
  87. <span class="pl-e">.Tweet.is-expanded</span> { <span class="pl-c">/* … */</span> }</pre></div>
  88. <div class="highlight highlight-html"><pre>&lt;<span class="pl-ent">article</span> <span class="pl-e">class</span>=<span class="pl-s"><span class="pl-pds">"</span>Tweet is-expanded<span class="pl-pds">"</span></span>&gt;
  89. &lt;/<span class="pl-ent">article</span>&gt;</pre></div>
  90. </article>