SemanSemantic-UItic-UI/server/documents/guide/styleguide.html.eco

  ---
layout      : 'default'
css         : 'guide'

title       : 'Language'
description : 'Suggestions for language usage when developing user interfaces'
type        : 'UI Guide'
---
<%- @partial('header') %>
<div class="main container">

  <div class="peek">
  <div class="ui vertical pointing secondary menu">
    <a class="active item">Language</a>
    <a class="item">Variations</a>
  </div>
  </div>

  <h2 class="ui dividing header">Language</h2>

  <p>Defining anything will involve some subjectivity. The goal of semantic is not to create code that is free from prescription, but to create code that tends to avoid arbitrary decisions if a conventional choice presents itself.</p>
  <p>The following are some guidelines which help avoid some common pitfalls in writing UI element definitions.</p>

  <div class="ui simple divider"></div>

  <h3 class="ui header">Neutral Base Form</h4>
  <p>In order to make UI components be able to exist in most websites, the prototype version of an element should be neutrally styled using greytones and neutral colors. This will allow other elements to be more robust giving other developers freedom to make decisions about color and style when adapting your element for their website.</p>

  <h3 class="ui header">Namespacing</h4>
  <p>All css code must live inside a namespace. By default all ui elements use the class "ui". This prevents rules from altering styles of other content in the page. This also helps differentiate between UI elements and parts of an element</p>
  <p>Tags inside of a ui element <b>do not</b> need to be prefixed with ui. They can simple descend from the element.</p>
    <div class="code" data-type="css">
    /* incorrect */
    .menu {

    }

    /* incorrect */
    .ui.menu .ui.item {

    }

    /* correct */
    .ui.menu {

    }
    .ui.menu .item {

    }
    </div>
  <h3 class="ui header">Commonality</h4>
  <p>Try to use the most obvious names for classes. If you're not sure, prototype the element, then ask a friend or two what they would call it.<p>
    <div class="code" data-type="css">
    /* hmm */
    .ginormous.ui.thingy {
      font-size: 1.5em;
    }
    /* better */
    .large.ui.thingy {
      font-size: 1.5em;
    }
    </div>

  <h3 class="ui header">Precision</h4>
  <p>Classes should be defined in one word, if the concept cannot be reduced to a single word then consider factoring it into multiple sub classes</p>
    <div class="code" data-type="css">
    .attached.ui.thingy {
      position: relative;
    }
    .left.attached.ui.thingy {
      left: 0px;
      top: 50%;
      margin-top: -0.5em;
    }
    .right.attached.ui.thingy {
      right: 0px;
      top: 50%;
      margin-top: -0.5em
    }
    </div>

  <h3 class="ui header">Use real words</h4>
  <p>Abbreviations are useful for taking notes, but css definitions should attempt to use consistent, common language.</p>
    <div class="code" data-type="css">
    /* nope */
    .ui.btn {

    }
    .ui.widget .cpttext {

    }
    /* good */
    .ui.button {

    }
    .ui.widget .caption {

    }
    </div>

  <h3 class="ui header">Non prescriptive</h4>
  <p>Avoid requiring any specific tags in your definitions. This will allow developers to choose which tags they would like to use with an element.</p>
  <p>Sometimes however it makes sense to allow for common tags to be used in place of classnames for brevity. Paragraph tags, links, labels, and tables may be useful to use in a UI element definition without classnames.</p>
  <p>Be cautious though, for example, requiring a form definition to use a form tag limits a developers ability to nest form elements inside other forms. The same is true for anchor tags</p>
    <div class="code" data-type="css">

    /* hey how do you know this is the third heading? */
    /* and what about all the other possible sizes?   */
    .ui.thingy h3 {

    }

    /* yay the developer can choose what type of heading tag to use */
    .ui.thingy .header {

    }
    </div>

    <div class="code" data-type="css">

    /* wow this guy is going to have to do a lot of typing... */
    .ui.table .cell {

    }
    /* this seems like a reasonable assumption, html is a bit strict about these things */
    .ui.table td {

    }
    </div>


  <h2 class="ui dividing header">Writing Variations</h2>

  <h3 class="ui header">Same but not the same</h4>
  <p>Multiple elements may contain similar variations that function slightly different.</p>
  <p>For example it may be useful for various elements to float left or right. At first it may seem most useful to write a helper class that floats all UI element types when given a certain class name, but the way which an element may be floated might vary depending on the type of element.</p>
    <div class="code" data-type="css">
    /*
    this element will default to floating left if any float is specified
    it will receive margins on its float relative to its size
    */
    .ui.floated.widget,
    .ui.left.floated.widget {
      float: left;
      margin-right: 1em;
    }
    .ui.right.floated.widget {
      float: right;
      margin-left: 1em;
    }
    /* this will not receive margins when floated and will default to floating right */
    .ui.floated.thingy,
    .ui.right.floated.thingy {
      float: right;
    }
    .ui.right.floated.thingy {
      float: left;
    }
    </div>

  <h3 class="ui header">Inversion</h4>
  <p>Elements are often inverted to stand out on dark backgrounds. Consider creating a variation of your element defines how the element can invert its colors.</p>
  <p>Keep in mind you might have to increase the contrast between shades of your element when inverting colors, its much easier to detect in a design between multiple shades of a light color than a dark one.</p>
    <div class="code" data-type="css">
    .ui.thingy {
      background-color: #FFFFFF;
      color: rgba(0, 0, 0, 0.7);
    }
    .ui.inverted.thingy {
      background-color: #222222;
      color: rgba(255, 255, 255, 0.7);
    }
    </div>


</div>