Merge branch 'release/1.1.2'

CHANGELOG.md

@@ -1,6 +1,14 @@
 
 # CHANGELOG
 
+*1.1.2* (2018-08-20)
+  - Add documentation new structure
+  - Add branding pages
+  - Add how to use the styleguide in your project
+  - Add illustrations to styleguide homepage
+  - add publication with left image
+  - Refactor collapse and lists component
+
 *1.1.1* (2018-08-13)
   - contact compact component
   - add date in headline
@@ -14,7 +22,7 @@
   - refactor homepage and full-width teaser usage
   - use object-fit property for fullwidth teasers
   - decrease fullwidth teaser content width
-  - add fallback grey background for highlights without image 
+  - add fallback grey background for highlights without image
   - implement card-deck component
   - Create the following pages:
     - Association homepage

VERSION

@@ -1 +1 @@
-1.1.1
+1.1.2

assets/components/atoms/alert/alert.yml

@@ -1,8 +1,13 @@
 title: Alert
 name: alert
+notes: |
+  Alerts help explain people what is going on in the system. Either for a success or a problem: the message should be clear. Green, blue and orange colours are specific to the alert component: **don't use them elsewhere**.
 variants:
   - name: types
     title: Alert types
     notes: |
-      The alert component supports all these color variants:<br>
-      `alert-success`, `alert-warning`, `alert-danger`, `alert-info`.
+      There is **4 variations** of the alert component:<br>
+      * `alert-success` — used to confirm a completed task or the successful submission of a form.
+      * `alert-info` — used to display an interesting yet non-critical information.
+      * `alert-warning` — used for unexpected events, that people must pay attention.
+      * `alert-danger` — used for critical information: an error or the unavailability of a service.

assets/components/atoms/button/button.yml

@@ -4,17 +4,27 @@ name: button
 variants:
   - name: states
     title: Primary states preview
+    notes: |
+      *For previewing purposes only. **Do not use in production!***
   - name: sizes
     title: Sizes preview
+    notes: |
+      You can use **4 different sizes**:
+      * **Small**: is suitable for an area where you don’t have many space to display a button.
+      * **Normal**: is the default size.
+      * **Large**: use with caution. This button draws people’s attention, leaving the rest of the content aside.
+      * **Block**: using all available width. Useful on mobile, when you want action to end a block (submit a form for instance).
   - name: secondary
     title: Button secondary
+    notes: |
+      Less important actions use secondary-style buttons. Two regular cases: give hierarchy next to a primary-style button ; for groups of buttons. Like in the footer for instance.
   - name: secondary-states
     title: Secondary states preview
+    notes: |
+      *For previewing purposes only. **Do not use in production!***
 notes: |
-  <br/>
-
-  *`.hover`, `.active` and `.focus` classes are used to simulated those states, don't use it in production.
-
+  Button is your interaction friend when you want people to complete an action. By clicking a button, people expect to trigger an event, confirm a form or load a new page. Don't put many buttons on one single page. The primary action should be obvious for people.
   <br/>
 
   ### Button primary
+  Main action in a page uses primary-style buttons. If you have more than one button in a page, **give hierarchy** to those different actions. You can use secondary button style or turn it into a link.

assets/components/atoms/checkbox/checkbox-states.twig

@@ -0,0 +1,4 @@
+<h5>Make your choice (multiple selection possible):</h5>
+{% include '@atoms/checkbox/checkbox.twig' with { id: '12', label: 'First choice' } %}
+{% include '@atoms/checkbox/checkbox.twig' with { id: '13', label: 'Choice number two' } %}
+{% include '@atoms/checkbox/checkbox.twig' with { id: '14', label: 'Three is for me!' } %}

assets/components/atoms/checkbox/checkbox.yml

@@ -1,2 +1,8 @@
 title: Checkbox
-name: checkbox
+name: checkbox
+variants:
+  - name: states
+    title: Checkbox list sample
+    notes: Here is a sample list with checkboxes.
+notes: |
+   Items list with checkboxes enable people to select some options, or none, or all. Use checkboxes for search options, selection in a form, policy acknowledgment, etc.

assets/components/atoms/collapse/collapse-title.twig

@@ -6,8 +6,9 @@
   aria-expanded="false"
   aria-controls="collapse-1"
 >
-  Collapse title
+  On the Origin of Species
 </button>
+
 <div class="collapse collapse-item collapse-item-desktop" id="collapse-1">
-  <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Architecto distinctio dolores fugiat modi necessitatibus officiis provident qui tempora ullam voluptas? Asperiores dolorem eius error esse nisi reprehenderit repudiandae ut! Eligendi.</p>
+  <p>Book by Charles Darwin, 1859 — On the Origin of Species, published on 24 November 1859, is a work of scientific literature by Charles Darwin which is considered to be the foundation of evolutionary biology.</p>
 </div>

assets/components/atoms/collapse/collapse.twig

@@ -1,10 +1,14 @@
-<p>
-  <button class="btn btn-primary collapsed" type="button" data-toggle="collapse" data-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
-    Collapse content
-  </button>
-</p>
-<div class="collapse" id="collapseExample">
-  <div class="card card-body">
-    Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident.
-  </div>
+<button
+  class="collapse-title collapse-title-desktop collapsed"
+  type="button"
+  data-toggle="collapse"
+  data-target="#collapse-1"
+  aria-expanded="false"
+  aria-controls="collapse-1"
+>
+  On the Origin of Species
+</button>
+
+<div class="collapse collapse-item collapse-item-desktop" id="collapse-1">
+  <p>Book by Charles Darwin, 1859 — On the Origin of Species, published on 24 November 1859, is a work of scientific literature by Charles Darwin which is considered to be the foundation of evolutionary biology.</p>
 </div>

assets/components/atoms/collapse/collapse.yml

@@ -1,9 +1,8 @@
 title: Collapse
 name: collapse
-variants:
-  - name: title
-    title: Collapse Title
-    notes: |
-      This component is **mobile only by default** as in the footer. To offer also the same behaviour on desktop, use the `collapse-title-desktop` and `collapse-item-desktop` classes like below.
 notes: |
-  The collapse JavaScript plugin is used to show and hide content. Buttons or anchors are used as triggers that are mapped to specific elements you toggle. Collapsing an element will `animate the height` from it’s current value to `0`. Given how CSS handles animations, you cannot use padding on a `.collapse` element. Instead, use the class as an independent wrapping element.
+  Collapse component contains chunks of content. You can **display or hide** this content by triggering it. Use it when content is dense and you want to suggest **extra readings**. The collapsed content should not be critical for the reader. You may also allow collapsible items to be open at the same time.
+
+  The collapse JavaScript plugin serves to show and hide content. Buttons or anchors are triggers mapped to the specific elements you toggle. Collapsing an element will `animate the height` from its current value to `0`. Given how CSS handles animations, you cannot use padding on a `.collapse` element. Instead, use the class as an independent wrapping element.
+
+  These elements are useful in groups. Use them to display various types of information, the most common use being **FAQ sections**. For more information, see the [content-group molecule](/#/molecules/collapse-group).

assets/components/atoms/definition-list/definition-list-grid.twig

@@ -1,16 +1,17 @@
+<h4>Informations utiles</h4>
 <dl class="definition-list definition-list-grid">
   <dt>Fonction</dt>
-  <dd>Fonction</dd>
+  <dd>Chercheur</dd>
   <dt>Unité</dt>
   <dd><a class="link-pretty" href="#">Laboratoire de métallurgie mécanique</a></dd>
-  <dt>Domaine de recherche</dt>
+  <dt>Domaines de recherche</dt>
   <dd>
     <a href="#" class="tag tag-primary">Inorganic Chemistry</a>
     <a href="#" class="tag tag-primary">Organic Chemistry</a>
     <a href="#" class="tag tag-primary">Renewable Energy</a>
   </dd>
   <dt>Bureau</dt>
-  <dd><a class="link-pretty" href="#">BM 4129</a></dd>
+  <dd><a class="link-pretty" href="#">BM 42</a></dd>
   <dt class="definition-list-item-full">A propos</dt>
-  <dd class="definition-list-item-full">Donec ullamcorper nulla non metus auctor fringilla. Vestibulum id ligula porta felis euismod semper. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit.</dd>
+  <dd class="definition-list-item-full">Research at the Laboratory of Mechanical Metallurgy addresses the science and engineering of advanced metallic materials. Our activities and interests span the entire spectrum from materials processing to the exploration of links between the microstructure and the properties of materials. Materials we study are made at least in part of metal and can be destined for structural or for functional applications.</dd>
 </dl>

assets/components/atoms/definition-list/definition-list.twig

@@ -1,8 +1,9 @@
+<h4>Terms definition list</h4>
 <dl class="definition-list">
-  <dt>Information scientifique et bibliothèques</dt>
-  <dd>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sit eum dolorem numquam aliquam! Sit dolores consequuntur est modi autem nobis qui dicta dolorem ipsa odio ipsum labore tempore esse, saepe quos repellendus, dolore at, minus expedita cum porro! Dolor, dolorum.</dd>
-  <dt>Domaine de la recherche</dt>
-  <dd>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sit eum dolorem numquam aliquam! Sit dolores consequuntur est modi autem nobis qui dicta dolorem ipsa odio ipsum labore tempore esse, saepe quos repellendus, dolore at, minus expedita cum porro! Dolor, dolorum.</dd>
-  <dt>Domaine de la <a href="#">recherche</a></dt>
-  <dd>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sit eum dolorem numquam aliquam! Sit dolores consequuntur est modi autem nobis qui dicta dolorem ipsa odio ipsum labore tempore esse, saepe quos repellendus, dolore at, minus expedita cum porro! Dolor, dolorum.</dd>
+  <dt>Exams and student assessment</dt>
+  <dd>All you need to know about exams: schedules, pass conditions, statements of results, what to do in case of illness on the day of an exam, what to do in case of failure, etc.</dd>
+  <dt>Internships</dt>
+  <dd>Internship exchange. Information on internships by Section.</dd>
+  <dt><a href="#">Special needs / course exemptions</a></dt>
+  <dd>Application procedure for course exemption. Application procedure for adapted curricula for disabled students or students with high-level sporting or musical activities.</dd>
 </dl>

assets/components/atoms/definition-list/definition-list.yml

@@ -1,11 +1,13 @@
 title: Definition list
 name: definition-list
 notes: |
-  The definition title can contain links.
+  The definition list component is a **set of definitions**. Every definition forme of two elements: a **term** to define, and a **definition** explaining its meaning. You can add links in both titles and texts. There is no hierarchy or levels in this list.
+
+  ### Standard definition list
 variants:
   - name: grid
-    title: Definition list as a Grid (table-like)
+    title: Grid definition list (table-like)
     notes: |
-      We sometimes need to display data in table-like layout. Definition list is great in these cases.
+      Definitions appear in a grid.
 
-      ♿️ Don't forget to add a title to the table, for a11y purposes.
+      ♿️ **Accessibility note**: Don't forget to add a title to the grid!

assets/components/atoms/drawer/drawer.yml

@@ -1,4 +1,4 @@
 title: Drawer
 name: drawer
 notes: |
-  Only used in the [Header light variant](#/organisms/header). Provide a link to the main website.
+  The drawer component serves one purpose only. **It enables people to go to EPFL’s main website.** This component should appear on all EPFL related websites, as part of their header. It is part of the “[Header light](#/organisms/header)” component.

assets/components/atoms/dropdown/dropdown.twig

@@ -7,4 +7,4 @@
     <a class="dropdown-item" href="#">Another action</a>
     <a class="dropdown-item" href="#">Something else here</a>
   </div>
-</div>
+</div>

assets/components/atoms/dropdown/dropdown.yml

@@ -1,2 +1,6 @@
 name: dropdown
 title: Dropdown
+notes: |
+  The dropdown component **triggers an action**. Use it when people need to perform an action in the page. Do not confuse this component with the [select component](#/atoms/select).
+
+  Remember to **keep lists useful**. Clear and short lists are the bests! Long lists slow the decision-making process. If you have few items (2 to 3), use other components, such as a [link](#/atoms/link) or a [button](#/atoms/button).

assets/components/atoms/figure/figure.twig

@@ -1,4 +1,4 @@
 <figure>
-  {% include '@atoms/picture/picture-one-third-square.twig' %}
+  {% include '@atoms/picture/picture-one-third.twig' %}
   <figcaption>Lorem ipsum dolor sit amet.</figcaption>
 </figure>

assets/components/atoms/figure/figure.yml

@@ -1,2 +1,5 @@
 title: Figure
-name: figure
+name: figure
+notes: |
+  This component is an entity that **is referenced in the flow of the page**. It's a visual version of the [sidenotes](#/molecules/sidenotes) or [footnotes](#/molecules/footnotes). It can contain an image, an illustration, a diagram or a code snippet. You can describe the element with a **caption**.
+  

assets/components/atoms/icon/icon.yml

@@ -1,9 +1,14 @@
 title: Icon
 name: icon
 notes: |
-  The icon component requires the icons sprite to be injected in the page to work. See `svg-icons.js` file.
+  Icons or pictograms are visual cues for interface elements, **use them sparingly**. Remember that icons should (almost) **always come with a label**. One of the exception being the magnyfing-glass icon for the search. This case is well recognized nowadays.
 
-  **♿️ Note**: the icon is hidden to screen readers with `aria-hidden="true"`, don't forget to add meaning to the component it is placed in (button, label, etc).
+  The icon component requires the icons sprite injected in the page to work. Please have a look at the `svg-icons.js` file.
+
+  **A11y note —**
+  The icon is hidden to screen readers with `aria-hidden="true"`, don't forget to add meaning to the component it is placed in (button, label, etc).
 variants:
   - name: list
-    title: Complete list
+    title: Icons list
+    notes: |
+      Here is the list of current available icons used in the styleguide.

assets/components/atoms/input/input.yml

@@ -3,19 +3,28 @@ name: input
 variants:
   - name: value
     title: With value
+    notes: |
+      Sample input with text content. Inputs can have pre-filled content that people can edit.
   - name: hover
     title: Hover*
+    notes: |
+      *For previewing purposes only. **Do not use in production!***
+      <br>*Represents the input when the mouse cursor hovers the component.*
   - name: focus
     title: Focus*
+    notes: |
+      *For previewing purposes only. **Do not use in production!***
+      <br>*Represents the input when you are editing the content inside the component.*
   - name: error
     title: Error
+    notes: |
+      The style to display when you perform validation in a form and that an error appears.
   - name: disabled
     title: Disabled
+    notes: |
+      You cannot edit the input content. A use case can be you want to show the entered content without allowing people to edit it.
 notes: |
-  <br/>
-
-  *`.hover` and `.focus` classes are used to simulate those states in the styleguide, don't use them in production.
-
-  <br/>
+  The input atom is the solution when you need people to submit text content. Inputs serve for search fields, forms, newsletter subscriptions, etc.
 
   ### Placeholder only
+  The basic component, a box with a placeholder text.

assets/components/atoms/link/link.yml

@@ -1,19 +1,23 @@
 title: Link
 name: link
 notes: >
-  A link is styled by default with a red underline (on [supported
-  browsers](https://caniuse.com/#feat=text-decoration), otherwise, the underline
-  uses the text color).
+  A link is a **navigation** component. Links are recognized as **doors between pages**. That means **links description** should be **self-explanatory**. People need to understand where they will land, if they click on a link. Avoid having long links. The **3-words-maximum** rule is good.
+  <br><br>
+  Links may - in some situations - activate interactions without loading a new the page. Like loading extra elements from a results list or sort items in a table.
+  <br>
 
+  ## Links styles
 
-  A `link-pretty` class can be used to create a better and more cross-browser
-  style.
+  Default style for links uses a **red underline**, in [supported
+  browsers](https://caniuse.com/#feat=text-decoration). In other browsers, the underline
+  uses text color.
 
-  A `link-collapse` class sets the link to have a red triangle and special
+  The `link-pretty` class creates a better and more cross-browser style.
+
+  The `link-collapse` class sets the link to have a red triangle and special
   styles.
 variants:
   - name: icon
     title: Icon
     notes: |
       You can set up a link with a custom icon. The icon will automatically be at the other end of the element (with flex).
-    wrapper: col-md-6

assets/components/atoms/list/list.yml

@@ -1,7 +1,7 @@
 name: list
 title: Lists
 notes: |
-  You can use classes to override the basic styles of lists. Use these in content areas.
+  The classic way to display a group of elements, with or without hierarchy. You can use `.list-numbered` and `.list-bullet` classes to override the basic styles of lists (see the variants lower on this page). Use lists in content areas.
 variants:
   - name: numbered
     title: Numbered list

assets/components/atoms/select/select-multiple.twig

@@ -1,8 +1,12 @@
-<select class="select-multiple" multiple="multiple" data-placeholder="Restaurant">
-  <option value="1">Chuck Testa</option>
-  <option value="4">Sage Cattabriga-Alosa</option>
-  <option value="3">Nikola Tesla</option>
-  <option value="2">I Love</option>
-  <option value="5">Pizza</option>
-  <option value="6">🍕</option>
-</select>
+<div class="form-group">
+	<label>Pick a restaurant</label>
+	<select class="select-multiple" multiple="multiple" data-placeholder="Restaurant list">
+	  <option value="1">Chuck Testa's tavern</option>
+	  <option value="2">The Sage Cattabriga-Alosa hideout</option>
+	  <option value="3">Nikola Tesla Drive-in</option>
+	  <option value="4">A Love for Pizza 🍕</option>
+	  <option value="5">The Hydron Collider </option>
+	  <option value="6">There's no place like 127.0.0.1</option>
+	  <option value="7">The Shake Shack Space bar</option>
+	</select>
+</div>

assets/components/atoms/select/select.twig

@@ -1,5 +1,11 @@
+<div class="form-group">
+<label>Choose wisely</label>
 <select id="select-input" class="custom-select">
   <option selected>Make a choice...</option>
   <option value="1">Legolas</option>
   <option value="2">Jar Jar Binks</option>
+  <option value="3">None of them</option>
+  <option value="4">The fourth choice</option>
+  <option value="5">42</option>
 </select>
+</div>

assets/components/atoms/select/select.yml

@@ -2,4 +2,10 @@ title: Select
 name: select
 variants:
   - name: multiple
-    title: Select multiple
+    title: Select multiple
+    notes: |
+      This variation of the select component enables **multiple choices**. Again, keep your list to the smallest. Think of having a “select all/none” item when the list is long.
+notes: |
+  The select component is mainly used in **forms**. Use it when people have to **choose options from a list**. The select component doesn't trigger actions: it stores a choice before submission. Don't use it when the number of options is low (2 to 3). Use the [checkboxes](#/atoms/checkbox) or [radio buttons](#/atoms/radio) instead. Pay  attention to **long lists**: beyond 7 or 8 options, people struggle to make a educated choice. In any case, keep your list below 15-ish items.
+
+  ### Standard select

assets/components/atoms/tag/tag.twig

@@ -1,9 +1,9 @@
-<h5>non-link</h5>
+<h5>Non-link</h5>
 <span class="tag tag-plain">Plain</span>
 <span class="tag tag-light">Light</span>
 
 <hr>
-<h5>link</h5>
+<h5>Link</h5>
 <a href="#" class="tag tag-primary">Primary</a>
 <a href="#" class="tag tag-secondary">Secondary</a>
 <hr>
@@ -17,7 +17,7 @@
   <a href="javascript:void(0)" class="remove" tabindex="-1" title="Remove">×</a>
 </span>
 <hr>
-<h5>small</h5>
+<h5>Small</h5>
 <span class="tag tag-sm tag-plain">Plain</span>
 <span class="tag tag-sm tag-primary">Primary</span>
 <span class="tag tag-sm tag-secondary">Secondary</span>